> ## Documentation Index
> Fetch the complete documentation index at: https://supahooks.ar27111994.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover from webhook failures with replay workflows

> Identify failed webhook events with log queries, review payload and error context, and replay captured events to a fixed endpoint for recovery.

When a webhook integration fails in production, you need to identify which events were affected, understand what went wrong, and re-deliver the original payloads to your fixed endpoint — without asking the provider to resend. The Webhook Debugger stores every captured event as a durable record and exposes a replay API that lets you re-send any stored event to a new destination.

## Recommended incident configuration

Start a new actor run with a long retention window and alerting enabled so you can capture and triage events over the full incident window:

```json theme={null}
{
  "urlCount": 1,
  "retentionHours": 168,
  "authKey": "incident-response-key",
  "enableJSONParsing": true,
  "maskSensitiveData": true,
  "defaultResponseCode": 200,
  "defaultResponseBody": "{\"buffered\":true}",
  "forwardUrl": "https://api.example.com/webhooks/reconcile",
  "forwardHeaders": true,
  "replayMaxRetries": 5,
  "replayTimeoutMs": 15000,
  "alerts": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/AAA/BBB/CCC"
    },
    "discord": {
      "webhookUrl": "https://discord.com/api/webhooks/AAA/BBB"
    }
  },
  "alertOn": ["error", "5xx", "signature_invalid"]
}
```

## Identify failed events

Use the `/logs` query API to find events that need attention. Authenticate with your `authKey` using the `Authorization` header:

```bash theme={null}
Authorization: Bearer <authKey>
```

**Find all events with a 4xx or 5xx status:**

```bash theme={null}
GET /logs?webhookId=wh_abc123&statusCode[gte]=400
```

**Find events that failed signature verification:**

```bash theme={null}
GET /logs?webhookId=wh_abc123&signatureValid=false
```

**Check forwarding and sync health:**

```bash theme={null}
GET /system/metrics
```

**Find a specific event by the actor-generated request ID:**

```bash theme={null}
GET /logs?requestId=req_abc123
```

**Confirm active webhook IDs and current configuration:**

```bash theme={null}
GET /info
```

**Watch live traffic while the incident is still active:**

```bash theme={null}
GET /log-stream
```

## Review payload and error context

Retrieve the full detail for a specific log entry:

```bash theme={null}
curl -H "Authorization: Bearer <authKey>" \
  "https://<run-id>.runs.apify.net/logs/evt_8m2L5p9xR"
```

The response includes headers, body, response status, signature state, and timing:

```json theme={null}
{
  "id": "evt_8m2L5p9xR",
  "webhookId": "wh_abc123",
  "timestamp": "2026-01-30T12:00:00.000Z",
  "method": "POST",
  "statusCode": 500,
  "signatureValid": true,
  "signatureProvider": "stripe",
  "headers": {
    "content-type": "application/json",
    "stripe-signature": "t=...,v1=..."
  },
  "body": {
    "type": "payment_intent.succeeded",
    "data": { "object": { "amount": 9999 } }
  }
}
```

If the body was offloaded to storage due to size, retrieve the full payload:

```bash theme={null}
curl -H "Authorization: Bearer <authKey>" \
  "https://<run-id>.runs.apify.net/logs/evt_8m2L5p9xR/payload"
```

<Note>
  If forwarding failed after a webhook was captured, the original ingress event is still stored independently, so the original payload is always available for replay. Check `/system/metrics` to see forwarding error counts and last sync time.
</Note>

## Replay to your fixed endpoint

Once you patch the downstream service, replay the original captured event. The actor sends the original method and payload, adds `X-Apify-Replay: true` and an idempotency key, and strips masked or transport-managed headers before forwarding.

**Replay a single event:**

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer <authKey>" \
  "https://<run-id>.runs.apify.net/replay/wh_abc123/evt_8m2L5p9xR?url=https%3A%2F%2Fapi.example.com%2Fwebhooks%2Freconcile"
```

A successful replay returns:

```json theme={null}
{
  "status": "replayed",
  "targetUrl": "https://api.example.com/webhooks/reconcile",
  "targetResponseCode": 200,
  "targetResponseBody": "OK"
}
```

## Bulk replay with offset pagination

To replay a large batch of failed events, page through `/logs` with `statusCode[gte]=400` and replay each entry. Use offset pagination to move through the full result set:

```bash theme={null}
GET /logs?webhookId=wh_abc123&statusCode[gte]=400&limit=100&offset=0
GET /logs?webhookId=wh_abc123&statusCode[gte]=400&limit=100&offset=100
GET /logs?webhookId=wh_abc123&statusCode[gte]=400&limit=100&offset=200
```

Each page response includes `nextOffset` and `nextPageUrl` for easy iteration:

```json theme={null}
{
  "count": 100,
  "total": 347,
  "nextOffset": 100,
  "nextPageUrl": "https://<run-id>.runs.apify.net/logs?webhookId=wh_abc123&statusCode[gte]=400&limit=100&offset=100"
}
```

For each `id` in the results, issue a replay request to your fixed endpoint.

<Tip>
  Keep `/log-stream` open during recovery to confirm each replayed request completes and to catch any follow-on errors immediately.
</Tip>

## Set up alerts to catch failures proactively

Configure `alertOn` with the failure conditions you want to know about immediately. The actor posts a notification to Slack or Discord when any matching condition occurs:

```json theme={null}
{
  "alertOn": ["error", "5xx", "signature_invalid"]
}
```

| Alert condition     | When it fires                                            |
| :------------------ | :------------------------------------------------------- |
| `error`             | An internal actor error occurs during request processing |
| `4xx`               | The actor returns a 4xx status to the sender             |
| `5xx`               | The actor returns a 5xx status to the sender             |
| `timeout`           | A forwarding or replay attempt times out                 |
| `signature_invalid` | An incoming request fails signature verification         |

## Common incident patterns

| Signal                                 | What it usually means                                                             | Next action                                                                                                                    |
| :------------------------------------- | :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| Forwarding errors in `/system/metrics` | The sender reached the actor but the downstream target failed later               | Fix the downstream target and replay the original captured event                                                               |
| `signatureValid=false`                 | Secret drift, body tampering, or provider clock skew                              | Correct the verification config before replaying — replaying an event to a handler that rejects bad signatures will fail again |
| Repeated 4xx or 5xx from the sender    | A forced status or the request path is rejecting traffic before normal processing | Confirm whether the failure is intentional, then inspect auth, IP restrictions, or schema validation                           |