Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions fern/server-url/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).
</Note>

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

<Note>
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).
</Note>

To see what Vapi sent and what your server returned for each delivery, open [Webhook logs](/observability/logs/webhook-logs).

### Function Calling (Tools)

<Info>
Expand Down
Loading