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.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.