Monitoring and Troubleshooting
Use this page to check the status of your webhooks and troubleshoot common webhook delivery problems.
For information about how the Webhooks service delivers events and handles failed deliveries, see Event Delivery Guarantees.
Check Webhook Status
Retrieve your webhooks and check the status property to determine the current state of a webhook.
The possible status values are:
| Status | Meaning |
|---|---|
active |
The webhook is active and the most recent notifications were delivered successfully. |
inactive |
The webhook was deactivated following delivery failures. |
reactivated |
The webhook was previously inactive and a reactivation attempt was made, but no event has been delivered since reactivation. |
You can use the status query parameter when retrieving webhooks to return webhooks with a specific status.
For more information about webhook properties, see the Webhooks Field Guide.
Retrieve the Relevant Hooks
Use the appropriate endpoint when checking the status or configuration of a webhook:
GET /webhooks/v1/hooksreturns webhooks visible to the access token holder. You can call this endpoint using a two-legged or three-legged access token.GET /webhooks/v1/app/hooksreturns webhooks created by the application. Use a two-legged access token to call this endpoint.
For more information about choosing the appropriate access token, see Authentication for Webhooks.
For instructions on retrieving webhooks, see Retrieve a List of Webhooks.
If a Callback Does Not Arrive
If an expected callback does not arrive, check the following:
- Verify that the webhook exists and that its
statusisactive. - Verify that the webhook was created before the event occurred.
- Verify that the event matches the event type registered for the webhook.
- Verify that the affected resource is within the webhook scope.
- Verify that the callback URL is reachable and can receive requests from the Webhooks service.
- If the webhook uses a
filter, verify that the event payload matches the filter expression.
For information about preparing a callback endpoint, see Configuring Your Server.
For information about filters, see Callback Filtering.
Delivery Failures and Inactivation
The Webhooks service retries failed event deliveries. Repeated delivery failures can cause a webhook to become inactive.
If a webhook becomes inactive:
- Fix the problem that is preventing the callback endpoint from successfully receiving events.
- Retrieve the webhook and check its current
status. - After the webhook is reactivated, verify that subsequent events are delivered successfully.
For details about retries, inactivation, and recovery behavior, see Event Delivery Guarantees.
Webhook Is Missing From the List
If a webhook does not appear when you retrieve webhooks:
- Verify that you are using the appropriate retrieval endpoint for the webhook.
- Verify that you are using an access token that can retrieve that webhook.
- Verify that you are retrieving webhooks from the same region in which the webhook was created. See Regionalization and Data Residency.
GET /webhooks/v1/hooks and GET /webhooks/v1/app/hooks return different sets of webhooks, so a webhook that does not appear in one list might be available through the other.
For more information about the two endpoints and their authentication requirements, see Authentication for Webhooks and Retrieve a List of Webhooks.
Common Errors When Calling the Webhooks API
The following errors can occur on any Webhooks API request, most often when creating a webhook.
Creating the webhook returns 401 or 403. The access token is missing, invalid, or lacks the required scopes, or the signed-in user lacks the permissions the operation requires. See Authentication for Webhooks.
Creating the webhook returns 400. The request body or path is malformed. Confirm that the scope name and event name are the ones the target system expects, and that the event name includes its version suffix, such as -1.0. Scope names and supported events differ by system; see the tutorial for the system you are subscribing to.
Creating the webhook returns 409. A webhook already exists for the same callback URL, scope, and event. Retrieve your existing webhooks before creating another.
Requests start returning 429. You have exceeded a rate limit. Wait for the period given in the Retry-After header, then retry. See Rate Limits and Quotas.
The Location header appears as location. HTTP header names are case-insensitive. If your connection uses HTTP/2, gateways and proxies return header names in lowercase, so Location may arrive as location. Look up response headers case-insensitively, as most HTTP client libraries already do by default, rather than relying on a specific case.
Some systems impose additional requirements, such as a specific permission or a particular access token type. For those, see the Before You Begin section and the Create the Webhook step of the tutorial for that system.