Webhook failures description

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

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

ParameterDescriptionTypeRequiredNotes
start_dateThe beginning of the date range to return failed webhooks.stringNoISO 8601 format. Must be within the past 31 days.
end_dateThe end of the date range to return failed webhooks.stringNoISO 8601 format. Must be after the start_date.
pagePage number for paginated results.integerNoDefault: 1
per_pageNumber of results per page.integerNoDefault: 50

Response

The following table describes the response structure:

ElementDescriptionType
failuresArray of failed webhook eventsarray
failures[].idUnique identifier of the failed webhookstring
failures[].eventEvent type associated with the webhookstring
failures[].reasonDescription of the failure reasonstring
failures[].statusCurrent status (e.g., failed)string
failures[].last_attemptTimestamp of last retry attempt (ISO 8601)string
pagination.totalTotal number of recordsinteger
pagination.pageCurrent page numberinteger
pagination.per_pageNumber of records per pageinteger

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.