Receive and verify 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.

OAuth (optional)

Webhooks support OAuth 2.0 client credentials. In the webhook’s create or edit form:

Turn on Use OAuth.
Enter your Token URL, Client ID, and Client secret.
Set Token timeout (minutes) to your token lifetime (default: 60).
Enter an API key only if your receiving endpoint requires one.
Select Create or Update to save.

Use public HTTPS URLs for both endpoints. The token endpoint must accept client_credentials with HTTP Basic client authentication.

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 webhook’s data object uses the same schema as data in the response from GET /benefit-verification/{id} or GET /prior-authorization/{id}. The webhook does not include the GET response’s outer envelope. Read data.status and the error or outcome fields as you would in that GET 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. Call GET /prior-authorization/{id} when you need the complete PA. Call the relevant GET endpoint above with data.id to check the latest BV or PA status after a webhook arrives.

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)

For a receiver configured to verify signed deliveries, reject the request if the X-Webhook-Secret header is missing or signature verification fails. Do this before accepting the event or changing application state.

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.

Start here

Benefit verification

Prior authorization

Integration

Receive and verify webhooks

Set up a webhook

OAuth (optional)

Receive webhook notifications

Verify webhook signatures

Best practices

​Set up a webhook

​OAuth (optional)

​Receive webhook notifications

​Verify webhook signatures

​Best practices

Set up a webhook

OAuth (optional)

Receive webhook notifications

Verify webhook signatures

Best practices