Recover from webhook failures with replay workflows

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:

{
  "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:

Authorization: Bearer <authKey>

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

GET /logs?webhookId=wh_abc123&statusCode[gte]=400

Find events that failed signature verification:

GET /logs?webhookId=wh_abc123&signatureValid=false

Check forwarding and sync health:

GET /system/metrics

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

GET /logs?requestId=req_abc123

Confirm active webhook IDs and current configuration:

GET /info

Watch live traffic while the incident is still active:

GET /log-stream

Review payload and error context

Retrieve the full detail for a specific log entry:

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:

{
  "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:

curl -H "Authorization: Bearer <authKey>" \
  "https://<run-id>.runs.apify.net/logs/evt_8m2L5p9xR/payload"

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.

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:

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:

{
  "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:

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:

{
  "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.

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

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:

{
  "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

Get Started

Core Features

Security

Configuration

Guides

Help

Recover from webhook failures with replay workflows

Recommended incident configuration

Identify failed events

Review payload and error context

Replay to your fixed endpoint

Set up alerts to catch failures proactively

Common incident patterns

​Recommended incident configuration

​Identify failed events

​Review payload and error context

​Replay to your fixed endpoint

​Bulk replay with offset pagination

​Set up alerts to catch failures proactively

​Common incident patterns

Recommended incident configuration

Identify failed events

Review payload and error context

Replay to your fixed endpoint

Bulk replay with offset pagination

Set up alerts to catch failures proactively

Common incident patterns