Webhooks

Webhooks notify your system when a Develop Health resource changes. The event_type identifies why the webhook was sent, and data contains the resource’s current state. Use the resource-specific guides to see when each event is sent:

Webhook delivery occurs only when your endpoint is enabled and subscribed to the relevant event type.

Set up a webhook

In the application sidebar, open Settings, then select Webhooks.

Select Create webhook, then provide:

Name: A name that identifies the webhook.
URL: The endpoint that receives notifications.
Secret key (recommended): An optional confidential value used to sign deliveries. Deliveries are unsigned when a secret is not configured.
Enabled: Leave this on to begin receiving notifications as soon as the webhook is created. Turn it off to save the configuration without sending notifications.
Event categories: Select Benefit verification, Prior authorization, or both.

Select Create. You can enable or disable the webhook later from the Webhooks settings section. Activation can take a moment.

Receive webhook notifications

Develop Health sends an HTTP POST request to your configured URL when a subscribed event occurs. Resource events use this envelope:

{
  "title": "Prior Authorization Updated",
  "description": "A Prior Authorization submission status or outcome has changed.",
  "event_type": "prior_authorization.status_change",
  "data": {
    "id": "pa_req_aBcDeFg",
    "object": "prior_authorization",
    "status": "awaiting_outcome"
    // ... See GET /prior-authorization/{id} for the complete schema
  }
}

The data object uses the response schema from the corresponding GET endpoint. The webhook does not include the GET endpoint’s outer response envelope. Use data.status and the product-specific error or outcome fields as you would in a retrieve response. The event_type identifies why the webhook was sent; it does not replace the resource state or imply that the resource is terminal. Prior authorization webhook delivery may omit the large evidence, visit_notes, and questionnaires fields; use the GET endpoint when you need the complete current resource. Use the resource ID to retrieve the latest complete representation. The resource snapshot is the source of truth; event_type identifies the change that prompted delivery.

Provider outreach events use a dedicated envelope with event_id, occurred_at, and a provider outreach object in data. See Provider outreach webhooks for the full contract.

Return a 2xx status code after durably accepting a notification. Develop Health may retry a delivery after a non-2xx response.

Verify webhook signatures

When a webhook secret is configured, each POST request contains an X-Webhook-Secret header with a JWT signed by that secret. Verify the JWT before processing the payload. Deliveries do not include this header when no secret is configured. Install PyJWT:

pip install PyJWT

Verify the signature using the HS256 algorithm:

import jwt


def is_jwt_valid(token: str, secret: str) -> bool:
    try:
        jwt.decode(token, secret, algorithms=["HS256"])
        return True
    except jwt.InvalidTokenError:
        return False


webhook_secret = "<x-webhook-secret-header-value>"
secret_key = "<secret-configured-for-the-webhook>"

is_jwt_valid(webhook_secret, secret_key)

Reject the request if signature verification fails.

Best practices

Keep the receiving endpoint highly available.
Return a 2xx response as soon as the event is durably accepted, then process it asynchronously.
Handle deliveries idempotently because retries can produce duplicates.
Tolerate new status, outcome, activity, and error values.
Log deliveries and monitor processing failures.
Use the corresponding GET endpoint when you need the latest complete resource.

Getting Started

Benefit Verification

Prior Authorization

Prior Authorization Status (Coming Soon)

Set up a webhook

Receive webhook notifications

Verify webhook signatures

Best practices

​Set up a webhook

​Receive webhook notifications

​Verify webhook signatures

​Best practices

Set up a webhook

Receive webhook notifications

Verify webhook signatures

Best practices