​
Why Use Webhooks?

Efficiency and Real-time Updates: Webhooks eliminate the need to frequently check the API for status updates, thereby reducing network traffic and server load. They provide real-time information as soon as the status changes, ensuring timely updates.

Customized Integration: Webhooks allow you to define a callback URL to receive notifications, offering flexibility in how and where you process these updates.

​
Supported Events

Webhooks can be configured for the following events

  • Benefit Verification Updated: A Benefit Verification has been updated.
  • Prior Authorization Determination: A coverage determination was received from the payer.

​
Setting Up Webhooks

To configure a webhook, visit the “Webhooks” section of the Admin panel

Admin Panel Webhooks Section

Click on “Add Webhook”, then enter the following information

  • Name: A name to identify the webhook.
  • URL: The url to which the notification will be sent.
  • Secret Key: Enter a value that is confidential. Do not share this value as it is used to secure the transaction.
  • Events: The event to be notified about.

Only subscribe to a specific event. Do not check the box for the group of events.

Admin Panel Add New Webhook

After creating the webhook, you should see the webhook in the Admin Portal. Toggle it on to activate notifications (this can take a moment).

Admin Panel Webhooks Section

Now a request will be sent to the provided url each time the event occurs in the Develop Health platform.

​
Receiving Webhook Notifications

When an event that you’re subscribed to happens, such as a benefit verification outcome, our server will send a POST request to the callback_url you specified. The payload of this POST request contains essential details regarding the benefit verification. The format of the webhook payload matches that of the GET /benefit-verification endpoint endpoint, with additional top-level fields for the event title and description.

{
  "title": "Benefit Verification Updated",
  "description": "A Benefit Verification has been updated.",
  "data": {
    "id": "bv_nBElDPw",
    "object": "benefit_verification",
    "status": "completed",
    // ... See the GET /benefit-verification endpoint docs for the full schema
}

Your endpoint should return a 2xx status code to acknowledge the receipt of the notification. If our server receives a non-2xx response, it may attempt to resend the notification.

​
Verifying Webhook Signatures

Webhook signatures are essential for ensuring that the data received at your endpoint is actually from Develop Health.

As part of creating the webhook you provided a secret. Each POST request sent to your callback URL contains a header X-Webhook-Secret which is a JWT signed using the secret. By verifying this signature, you validate that the request was sent from the Develop Health platform.

​
Verifying Webhook Signature in Python

The following is an example of how to verify the webhook signature in Python.

First, you need to install the PyJWT library. You can do this using pip:

pip install PyJWT

Then, you can use the following Python code to verify the JWT:

import jwt

def is_jwt_valid(token: str, secret: str) -> bool:
    try:
        # Decode the token with the provided secret
        # The algorithm used to sign the token should be specified (e.g., HS256)
        decoded_token = jwt.decode(token, secret, algorithms=["HS256"])
        print("Token is valid.")
        return True
    except jwt.InvalidSignatureError:
        print("Invalid signature.")
    except jwt.ExpiredSignatureError:
        print("Token has expired.")
    except jwt.InvalidTokenError:
        print("Invalid Token.")
    return False

# Example usage
webhook_secret = "<x-webhook-secret-value>"  # The value from the x-webhook-secret header
secret_key = "<the secret in the dashboard on webhook settings>"  # The secret key you set in the dashboard

is_jwt_valid(webhook_secret, secret_key)

​
Failure to Verify

If the signature does not verify, log the event and reject the webhook as it might have been sent from an untrusted source.

​
Conclusion

By incorporating signature verification, you add an extra layer of security to ensure that the webhook notifications your system processes are legitimate and unaltered. This approach mirrors best practices used by leading companies like Stripe, enhancing the trustworthiness and reliability of your webhook integration.

​
Webhook Best Practices

  • Endpoint Availability: Ensure that your webhook endpoint is always available to receive updates.
  • Idempotency: Design your webhook handling logic to be idempotent to gracefully handle duplicate notifications.
  • Logging and Monitoring: Maintain logs of received webhooks and monitor for any unexpected behavior or failures.
  • Timely Processing: Process webhook notifications promptly to keep the authorization status updated in your systems.

By following these guidelines, you can efficiently integrate with our webhook system to receive timely updates about benefit verification statuses, enhancing your application’s responsiveness and reliability.

Authentication