Fix failed deliveries

# Fix failed deliveries

Use this guide when deliveries are failing, a subscription has been disabled, or events you expected never arrived.

## 1. Check the subscription

In Drum, open your user menu, select **Profile**, then **Webhooks**, and open the subscription.

| You see | It means |
| --- | --- |
| **Active**, with consecutive failures | Deliveries are failing, but Drum is still sending |
| **Paused** | Someone paused it. Nothing is sent, and events while paused are lost |
| **Disabled**, with a **Disabled reason** | Drum stopped sending. "Too many consecutive failures (10)" means 10 deliveries in a row failed. "Webhook URL blocked due to security policy" means the URL points to an address Drum will not send to |

Drum emails the person who created the subscription when it disables one.

## 2. Read the failed deliveries

The delivery log is in the API. With a token whose user has `manage_webhooks`, list the subscription's deliveries:

```bash
curl https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries \
  -H "Authorization: Bearer $DRUM_TOKEN"
```

Each delivery has a `status`, an `attempt_count`, the last `response_status` and an `error_message`. Open one to see the body Drum sent and what your endpoint answered:

```bash
curl https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries/991 \
  -H "Authorization: Bearer $DRUM_TOKEN"
```

Drum keeps successful deliveries for 30 days and failed ones for 90 days.

## 3. Fix the cause

| `error_message` or response | Fix |
| --- | --- |
| `HTTP 401` or `HTTP 403` | Your endpoint rejected the request. Check the secret and the [signature check](/webhooks/how-to/verify-webhook-signatures/#if-signatures-never-match) |
| `HTTP 404` or `HTTP 405` | The URL is wrong, or the route does not accept `POST` |
| `HTTP 5xx` | Your endpoint failed. Check its logs at the delivery's time |
| `Faraday::TimeoutError` | Your endpoint took more than 30 seconds. Return `200` first and do the work in the background |
| `Faraday::ConnectionFailed` | Drum could not connect. The host is down, or not reachable from the internet |
| An SSL error | The certificate is expired, self-signed, or for a different host name |
| `Blocked: ...` | The URL resolves to a private, loopback or cloud metadata address. Use a public address |

## 4. Re-activate the subscription

If the subscription is **Disabled**, select **Re-activate** on its page, or call `PATCH /api/v1/webhook_subscriptions/41/resume`. This also resets the failure count.

Re-activate only after the fix. If the next 10 deliveries fail, Drum disables it again.

## 5. Send failed deliveries again

Drum does not resend a failed delivery by itself. For each one you need, call `retry`:

```bash
curl -X POST https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries/991/retry \
  -H "Authorization: Bearer $DRUM_TOKEN"
```

The response is `202` with the id of a new delivery. It sends the same body as the original, as it was when the event happened, with a new `X-Webhook-Delivery-Id`.

- The subscription must be active, or the new delivery waits and is not sent.
- A delivery that succeeded cannot be retried (`422`).
- If the record has changed since, your endpoint receives an older state. Keep the event with the latest `data.attributes.updated_at` for each record, so an old retry does not overwrite newer data.

When many events were lost, or they are older than 90 days, it can be simpler to read the current records through the [REST API](/api/) and reconcile.

## If nothing arrives at all

| Check | Why |
| --- | --- |
| The subscription is **Active** | Paused and disabled subscriptions send nothing |
| It includes the event | Each subscription sends only its selected events |
| The event fires for this change | For example, `project.completed` is only for delivery projects. See [Events](/webhooks/reference/events/) |
| The change was not made by a bulk process | Some imports and bulk changes send one event at the end, or none. See [Events](/webhooks/reference/events/#project-events) |
| Your endpoint is reachable from the internet over HTTPS | Drum does not send to `http`, `localhost` or private addresses |
| No deliveries are listed at all | Drum made no delivery, so the event did not fire for this subscription. Check the first three rows |

Use this guide when deliveries are failing, a subscription has been disabled, or events you expected never arrived.

1. Check the subscription

In Drum, open your user menu, select Profile, then Webhooks, and open the subscription.

You see	It means
Active, with consecutive failures	Deliveries are failing, but Drum is still sending
Paused	Someone paused it. Nothing is sent, and events while paused are lost
Disabled, with a Disabled reason	Drum stopped sending. “Too many consecutive failures (10)” means 10 deliveries in a row failed. “Webhook URL blocked due to security policy” means the URL points to an address Drum will not send to

Drum emails the person who created the subscription when it disables one.

2. Read the failed deliveries

The delivery log is in the API. With a token whose user has manage_webhooks, list the subscription’s deliveries:

curl https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries \
  -H "Authorization: Bearer $DRUM_TOKEN"

Each delivery has a status, an attempt_count, the last response_status and an error_message. Open one to see the body Drum sent and what your endpoint answered:

curl https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries/991 \
  -H "Authorization: Bearer $DRUM_TOKEN"

Drum keeps successful deliveries for 30 days and failed ones for 90 days.

3. Fix the cause

`error_message` or response	Fix
`HTTP 401` or `HTTP 403`	Your endpoint rejected the request. Check the secret and the signature check
`HTTP 404` or `HTTP 405`	The URL is wrong, or the route does not accept `POST`
`HTTP 5xx`	Your endpoint failed. Check its logs at the delivery’s time
`Faraday::TimeoutError`	Your endpoint took more than 30 seconds. Return `200` first and do the work in the background
`Faraday::ConnectionFailed`	Drum could not connect. The host is down, or not reachable from the internet
An SSL error	The certificate is expired, self-signed, or for a different host name
`Blocked: ...`	The URL resolves to a private, loopback or cloud metadata address. Use a public address

4. Re-activate the subscription

If the subscription is Disabled, select Re-activate on its page, or call PATCH /api/v1/webhook_subscriptions/41/resume. This also resets the failure count.

Re-activate only after the fix. If the next 10 deliveries fail, Drum disables it again.

5. Send failed deliveries again

Drum does not resend a failed delivery by itself. For each one you need, call retry:

curl -X POST https://app.getdrum.com/api/v1/webhook_subscriptions/41/webhook_deliveries/991/retry \
  -H "Authorization: Bearer $DRUM_TOKEN"

The response is 202 with the id of a new delivery. It sends the same body as the original, as it was when the event happened, with a new X-Webhook-Delivery-Id.

The subscription must be active, or the new delivery waits and is not sent.
A delivery that succeeded cannot be retried (422).
If the record has changed since, your endpoint receives an older state. Keep the event with the latest data.attributes.updated_at for each record, so an old retry does not overwrite newer data.

When many events were lost, or they are older than 90 days, it can be simpler to read the current records through the REST API and reconcile.

If nothing arrives at all

Check	Why
The subscription is Active	Paused and disabled subscriptions send nothing
It includes the event	Each subscription sends only its selected events
The event fires for this change	For example, `project.completed` is only for delivery projects. See Events
The change was not made by a bulk process	Some imports and bulk changes send one event at the end, or none. See Events
Your endpoint is reachable from the internet over HTTPS	Drum does not send to `http`, `localhost` or private addresses
No deliveries are listed at all	Drum made no delivery, so the event did not fire for this subscription. Check the first three rows