> This page is for version 2022-09-01.
> For other versions, use one of these documentation indexes:
> - 2025-12-08 (default): https://docs.withpersona.com/2025-12-08/llms.txt
> - 2025-10-27: https://docs.withpersona.com/2025-10-27/llms.txt
> - 2023-01-05: https://docs.withpersona.com/2023-01-05/llms.txt
> - 2022-09-01: https://docs.withpersona.com/2022-09-01/llms.txt
> - 2021-07-05: https://docs.withpersona.com/2021-07-05/llms.txt
> - 2021-05-14: https://docs.withpersona.com/2021-05-14/llms.txt
> - 2020-05-18: https://docs.withpersona.com/2020-05-18/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Webhook Failure Alerts

## Description

Webhook Failure Alerts notify your team when a webhook's endpoint stops accepting deliveries, so you can fix it before events pile up in [retries](/webhooks#retry-logic).

You set a **failure threshold** and a **window** on each webhook, for example 100 failed deliveries within 15 minutes. When a webhook reaches its threshold, everyone on your team who has opted in to webhook delivery failure notifications, and who can view that webhook, is alerted.

Alerts are off until you configure them: a webhook without a threshold is never tracked, and teammates only receive alerts after they opt in.

## What counts as a failure

Only a webhook event's **first delivery attempt** is counted. Retries of the same event are not, so a single failing event can never trigger an alert on its own.

A delivery attempt fails when your endpoint doesn't respond with one of the [successful status codes](/webhooks#retry-logic) (`200`, `201`, `202` or `204`), including when the request times out or the connection fails.

## Configure a webhook's threshold

1. In the Dashboard, go to **Webhooks** and select the webhook.
2. In the **Failure alerts** card, set:
   * **Failure alert threshold**: how many failed deliveries trigger an alert. Any whole number of 1 or more.
   * **Failure alert window (minutes)**: how long to count failures for. Between 5 and 1,440 minutes (1 day).
3. Save the webhook.

Set both fields to turn alerts on, or clear both to turn alerts off for this webhook for everyone. Each webhook has its own threshold, so a busy production webhook and a quiet sandbox webhook can be tuned separately.

> **Note**
>
> The threshold and window are settings on the webhook, shared by everyone on your team: changing them changes when all opted-in teammates are alerted. To stop receiving alerts yourself without affecting anyone else, turn off **Delivery failures** in your notification settings instead.

> **Tip**
>
> #### Choosing a threshold
>
> Pick a number your webhook doesn't reach on a normal day. A threshold of `1` alerts on the first failed delivery, which suits low-volume webhooks where any failure matters. For high-volume webhooks, start higher and lower it if alerts arrive too late.

## Opt in to notifications

Each teammate chooses whether to receive these alerts:

1. Open your [notification settings](https://app.withpersona.com/dashboard/user/profile/notifications#webhooks) (**Profile** → **Notifications**).
2. Under **Webhooks**, turn on **Delivery failures** for **Dashboard**, **Email**, or both.

Alerts are only sent to teammates who can view webhooks in that environment, and not for environments they have muted in their notification settings.

## What you receive

When a webhook reaches its threshold, opted-in teammates receive a notification like:

> Webhook **Orders sync** had 100 failed deliveries within a 15-minute window (most recent: HTTP 406). Check that its endpoint is reachable and accepting requests.

The notification links to the webhook so you can review its recent events. The most recent response shows the HTTP status code your endpoint returned, or that there was no response when the request timed out or couldn't connect.

## How alerts are timed

* **One alert per webhook per day.** After a webhook alerts, it won't alert again for 24 hours, even if it keeps failing. If it is still failing after that, it alerts again the next time it reaches its threshold.
* **Fixed windows.** Failures are counted in fixed blocks of time rather than a rolling window. For example, 15-minute windows run from :00 to :15, :15 to :30, and so on (UTC). A burst of failures that straddles two blocks may not reach the threshold in either, in which case the alert arrives one window later if the failures continue.
* **Delivery is unaffected.** Alerts never change how Persona delivers or retries your webhook events.