Skip to main content

​
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 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.
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 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
}
Your endpoint should return a 2xx status code to acknowledge receipt of the notification. If our server receives a non-2xx response, it may attempt to resend the notification.

​
Event Types

The event_type value may be one of the following:
Event TypeTitleDescription
benefit_verification.status_changeBenefit Verification UpdatedA Benefit Verification has been updated.
prior_authorization.status_changePrior Authorization UpdatedA Prior Authorization submission status or outcome has changed.
prior_authorization.activity_log_updatedPrior Authorization Activity Log UpdatedThe activity log of a Prior Authorization has been updated.
prior_authorization.messagePrior Authorization MessageA message has been added to a Prior Authorization.
prior_authorization.prescription_transfer_changePrior Authorization Prescription Transfer UpdatedThe prescription transfer for a Prior Authorization has been updated.
prior_authorization.real_time_benefits_check_changePrior Authorization Real-Time Benefits CheckA real-time benefits check for a Prior Authorization has completed.
  • 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.message: Emitted when a message is added to a prior authorization’s message thread. This includes messages sent by your team through the dashboard as well as responses from the Develop Health team. See Platform Messages below for more details.
  • 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.
Prior authorization requests that are in completed status will not emit more prior_authorization.status_change events, but may still emit other event types such as prior_authorization.activity_log_updated or prior_authorization.message.

​
Platform Messages

The prior_authorization.message event is emitted whenever a message is added to a prior authorization’s message thread. This enables real-time notifications for back-and-forth communication about a PA request between your team and the Develop Health team. Messages can be sent through the Develop Health dashboard. You will receive a webhook for every message added to the thread, including responses from the Develop Health team.

​
Message Webhook Payload

The payload follows the same structure as other prior authorization webhooks — the data field contains the full prior authorization object (matching the GET /prior-authorization response), not the individual message. 
{
  "title": "Prior Authorization Message",
  "description": "A message has been added to a Prior Authorization.",
  "event_type": "prior_authorization.message",
  "data": {
    "id": "pa_req_aBcDeFg",
    "object": "prior_authorization",
    "status": "processing",
    // ... See the GET /prior-authorization endpoint docs for the full schema
  }
}
The message thread (including all message content) is included in the data.message_thread field of the prior authorization object. You do not need a separate API call to retrieve the message content.

​
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.