The Webhook failures API lets you retrieve a list of the webhooks that have become inactive and may need to be retriggered.
This legacy information is part of v1, v2, or v3, which will be supported only until March 31, 2027. To avoid disruption, migrate your integration to v4 before that date. For endpoint mappings, Bearer token authentication, and scoped API key guidance, see the Migrating to v4 article in the Developer's Guide.
Please refer to the detailed API endpoint specification: Webhook failures
Purpose
This API allows you to retrieve a summary of all webhook events that have entered an Inactive state due to repeated delivery failures. This helps you identify delivery gaps and take corrective action.
About the Inactive state
A webhook enters the Inactive state after it fails delivery five times in a 24-hour window. Failures are triggered by timeouts or non-2xx HTTP responses. Once in this state, the webhook is no longer retried by the system and must be manually reviewed or re-triggered.
Prerequisites
- You must have access to your contact center API key.
Making requests
Authentication
The webhooks API requires the Base URL and the contact center API key.
Endpoint
GET /api/webhooks/v1/failuresRequest parameters
This API uses the contact center API key in the Authorization: Bearer token in the header.
{
"method": "GET",
"url": "https://cluster1.contact_center_name.com/api/webhooks/v1/failures",
"headers": {
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
"params": {
"start_date": "2024-06-01T00:00:00Z",
"end_date": "2024-06-30T23:59:59Z",
"page": 1,
"limit": 50
}
}Query Parameters
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| start_date | The beginning of the date range to return failed webhooks. | string | No | ISO 8601 format. Must be within the past 31 days. |
| end_date | The end of the date range to return failed webhooks. | string | No | ISO 8601 format. Must be after the start_date. |
| page | Page number for paginated results. | integer | No | Default: 1 |
| limit | The maximum number of failed webhooks to return. | integer | No | Default: 50 |
Response
The following table describes the response structure:
| Element | Description | Type |
|---|---|---|
| failures | Array of failed webhook events | array |
| failures[].id | Unique identifier of the failed webhook | string |
| failures[].event | Event type associated with the webhook | string |
| failures[].reason | Description of the failure reason | string |
| failures[].status | Current status (e.g., failed) | string |
| failures[].last_attempt | Timestamp of last retry attempt (ISO 8601) | string |
| pagination.total | Total number of records | integer |
| pagination.page | Current page number | integer |
| pagination.per_page | Number of records per page | integer |
Response sample
{
"failures": [
{
"id": "aabbccddeeff",
"event": "call.ended",
"reason": "Connection timeout",
"status": "failed",
"last_attempt": "2025-07-01T10:32:14Z"
}
],
"pagination": {
"total": 1,
"page": 1,
"per_page": 50
}
}Troubleshooting
Invalid or missing API key
If you see this error, "error": "Invalid API key", ensure the contact center API key is passed in the Authorization header. Refer to Authentication.
Date range exceeds 31 days
If you see this error, "error": "start_date must be within the last 31 days", the start_date you specified is too far in the past.
end_date is before start_date
If you see this error, "error": "end_date must be after start_date", check that the end_date is chronologically after the start_date.
General API errors
For throttling, permission, or structural issues, confirm that the request complies with the Voiso API framework. See Authentication for more details.