The Webhook failures API lets you retrieve a list of the webhooks that have become inactive and may need to be retriggered.
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/failures
Request parameters
This API uses the contact center API key in the Authorization: Bearer token
in the header.
{
"method": "GET",
"url": "https://cluster1.voiso.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,
"per_page": 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 |
per_page | Number of results per page. | 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.