From 5ccd7ddcdae00e734d5770d83c1b5e48fc210620 Mon Sep 17 00:00:00 2001 From: Steve Smtih Date: Mon, 16 Nov 2026 05:07:08 -0800 Subject: [PATCH] Document server event delivery, timeouts, and retries --- fern/server-url/events.mdx | 46 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/fern/server-url/events.mdx b/fern/server-url/events.mdx index b5bec30ac..e85813e13 100644 --- a/fern/server-url/events.mdx +++ b/fern/server-url/events.mdx @@ -36,6 +36,52 @@ To inspect recorded server-message deliveries and responses, see [Webhook logs]( Monitoring alerts are a separate webhook. When a monitor detects an issue, Vapi sends an `issue.created` message to your notifier endpoint rather than the assistant Server URL. Its payload is documented in [Monitoring](/observability/monitoring-quickstart#webhook-payload). +### Delivery, timeouts, and retries + +Vapi sends each event as an HTTP `POST` to the [Server URL](/server-url/setting-server-urls) with the highest priority for that event. Your server's response depends on the message type: + +| Message type | What your server returns | Time limit | +| --- | --- | --- | +| `assistant-request` | An `assistantId`, a transient `assistant`, a `destination`, or an `error` | 7.5 seconds end-to-end. This limit is fixed. | +| `tool-calls` | HTTP 200 with a `results` array, one entry per `toolCallId` | The Server URL's timeout | +| `transfer-destination-request` | A `destination`, or an `error` to refuse the transfer | The Server URL's timeout | +| `knowledge-base-request` | A `documents` array | The Server URL's timeout | +| All other types, such as `status-update`, `transcript`, and `end-of-call-report` | No response body is needed. | The Server URL's timeout | + +The Server URL's timeout is 20 seconds by default. You can set it from 1 to 300 seconds with `timeoutSeconds` in the server configuration or with the **Timeout** setting in the Dashboard. + +#### Retries + +By default, Vapi doesn't retry a server message request that fails or times out. To retry, add a `backoffPlan` to the server configuration: + +```json +{ + "server": { + "url": "https://example.com/webhook", + "timeoutSeconds": 20, + "backoffPlan": { + "type": "exponential", + "maxRetries": 3, + "baseDelaySeconds": 1, + "excludedStatusCodes": [400, 401, 403, 404] + } + } +} +``` + +| Field | Description | +| --- | --- | +| `type` | `fixed` waits `baseDelaySeconds` between retries. `exponential` starts at `baseDelaySeconds` and increases the delay on each retry. | +| `maxRetries` | The number of retries, from 0 to 10. The default is 0, which means no retries. | +| `baseDelaySeconds` | The base delay, from 0 to 10 seconds. | +| `excludedStatusCodes` | Response status codes that are not retried. Without this list, any non-2xx response is retried. | + + + A retry can deliver the same event more than once, so make your handler safe to run twice for the same event. Use the `call.id` field to match events to a call. API Request tools don't retry after a failed response or a timeout, even when a `backoffPlan` is set. See [Handle latency and retries](/tools/api-request/reliability). + + +To see what Vapi sent and what your server returned for each delivery, open [Webhook logs](/observability/logs/webhook-logs). + ### Function Calling (Tools)