Webhooks

​

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. You will just receive a single event when the benefit verification has completed/failed.
• Prior Authorization Updated: A Prior Authorization has been updated. You will receive a notification for every status change of the prior authorization as well as other important updates. See the Prior Authorization API for more details on the statuses, and see the Event Types section below for the list of events that trigger webhooks.

​

Setting Up Webhooks

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

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.

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

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 objects GET endpoint with additional top-level fields for the event title and description. i.e. for Benefit Verifications refer to the GET /benefit-verification endpoint endpoint and for Prior Authorizations refer to GET /prior-authorization endpoint

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

​

Event Types

The event_type value may be one of the following:

• benefit_verification.status_change: Emitted when the status of a benefit verification changes.
• prior_authorization.status_change: Emitted when the status of a prior authorization changes.
• prior_authorization.activity_log_updated: Emitted when the activity log of a prior authorization is updated. This is disabled by default and can be enabled by contacting support.
• prior_authorization.prescription_transfer_change: Emitted when the prescription transfer for a prior authorization has an update. These events occur after the PA request is in “completed” status each time an attempt has been made to transfer the prescription, confirm the transfer, or the transfer is completed/terminated. Prescription transfer only happens for PA requests with an associated prescription that has been transferred to Develop Health.
• prior_authorization.real_time_benefits_check_change: Emitted when a real-time benefits check for a prior authorization is completed. This event may occur at any time, for example while the PA request is in “created” status before it begins processing, or after the PA has reached “completed” status. Real-time benefits check only happens for PA requests with an associated prescription that has been transferred to Develop Health.

​

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.