Webhook replay on agent connect: recover missed webhooks

Internal destinations depend on a running Webhook Relay agent. If a webhook arrives while no matching agent is connected, the request is persisted in the received state but cannot reach your service. Here, replay means authorized redelivery of a stored request after downtime, not a malicious webhook replay attack.

Enable Replay missing on connect on an internal output to recover those requests automatically. Each time a matching agent connects, Webhook Relay finds eligible received requests within your configured time range and sends them directly to that connection.

How replay on connect works

Replay is configured separately for each output destination:

1. A webhook arrives while no matching agent is available.
2. Webhook Relay persists the request and its output delivery remains received.
3. An agent connects and subscribes to the bucket or output.
4. Webhook Relay scans the configured lookback window for eligible received requests.
5. The selected requests are replayed oldest-first to preserve event order.
6. Successful deliveries update the existing request log entries to sent; replay does not create duplicate log entries.

The scan runs on every agent connection, including reconnects after a restart or network interruption. Live webhooks continue through the normal delivery path.

Enable automatic replay

1. Open Buckets in the Webhook Relay dashboard and select your bucket.
2. Select the internal output destination delivered through the relay agent.
3. On the output settings page, find Replay missing on connect.
4. Turn on Replay missing.
5. Choose a Time range and Maximum webhooks, then select Save.

The dashboard provides lookback windows of 8 hours, 24 hours, 3 days and 7 days. The maximum can be set to 10, 100, 1,000 or 5,000 webhooks.

What the maximum controls

The maximum limits how many of the newest received log rows Webhook Relay considers during one connection. After collecting those rows, it replays the eligible requests oldest-first.

For example, with a maximum of 100, the scanner considers the newest 100 received rows in the lookback window, then delivers the eligible ones from oldest to newest. Rows excluded by request-level connection filters or a status re-check still count toward the scan limit. The server maximum is 5,000 by default.

When replay is available

Replay on connect is available only when all of the following are true:

• The output is internal and delivered through a relay agent.
• The bucket uses persistent storage; zero-retention (ephemeral) buckets cannot replay request bodies or headers.
• The output does not use throughput throttling. Throttling already owns queued requests in the received state.
• The output is not used to return a synchronous custom response. Replaying later could repeat side effects after the original caller already timed out.
• The output and its replay configuration are enabled.

If an output is not eligible, the dashboard disables the switch and explains why.

Replay on connect versus durable retries

Both features improve delivery reliability, but they recover different failures:

For an internal destination, use replay on connect to cover agent downtime. Use durable retries when you also need long-running retries after the agent attempts delivery but the destination returns an error.

API configuration

The setting is stored on the output as replay_missing. REST API duration values use nanoseconds, so this example configures an 8-hour lookback and a 100-row scan limit:

{
  "replay_missing": {
    "enabled": true,
    "lookback": 28800000000000,
    "limit": 100
  }
}

API clients can use any positive lookback up to 124 days. The limit must be positive and cannot exceed the server's configured maximum, which is 5,000 by default.

When using Webhook Relay's MCP tools, the equivalent lookback is a readable Go duration string such as "8h" or "72h".

Make replay safe

Replayed requests are the original webhooks, including their original headers and body. Keep these considerations in mind:

• Make the receiver idempotent. A reconnect can overlap with live delivery, and webhook systems generally provide at-least-once rather than exactly-once delivery. Deduplicate using a stable event ID.
• Expect old timestamps and signatures. A provider's timestamp tolerance or short-lived signature may have expired before the agent reconnects. Only enable replay when the receiver can safely accept delayed requests.
• Prepare for bursts. The agent begins draining the selected backlog when it connects. Set the maximum to a volume the destination can absorb.
• Preserve ordering assumptions carefully. The selected backlog is replayed oldest-first per output, but new live requests can arrive while that backlog is being processed.

Frequently asked questions

How do I replay webhooks that arrived while a relay agent was offline?

Enable Replay missing on connect for the internal output. Set a lookback window and maximum, then save the output. When a matching agent connects or reconnects, Webhook Relay automatically finds eligible received requests and sends them to that agent.

Does Webhook Relay replay missed webhooks automatically?

Yes, after replay is enabled for an eligible internal output. The connection event triggers the scan, so no manual replay action is required after an agent restart or network interruption.

Which webhooks are replayed, and in what order?

Webhook Relay considers the newest received rows inside the configured lookback window, up to the configured maximum. After filters and a status re-check, the eligible requests are delivered oldest-first. New live requests can still arrive while the backlog is draining.

What is the difference between webhook replay and webhook retry?

Replay on connect recovers requests that never reached an offline agent. Durable retry recovers delivery attempts that reached an endpoint but failed or timed out. An internal output can use both features because they cover different failure stages.

Can webhook replay cause duplicate processing?

It can. A reconnect may overlap with live delivery, and the sender cannot guarantee exactly-once processing at the receiver. Make the receiver idempotent and deduplicate requests using a stable provider event ID or another application-level key.

What happens if the original webhook signature has expired?

Replay preserves the original body and headers. A provider signature with a short timestamp tolerance may therefore fail validation after a long outage. Configure a suitable lookback and ensure the receiver has a safe policy for delayed, authentic requests.

How many webhooks can be replayed on one connection?

The dashboard supports limits of 10, 100, 1,000 and 5,000. The server maximum is 5,000 by default. API clients can configure a positive lookback of up to 124 days, subject to that server limit.

Is replay on agent connect a webhook replay attack?

No. It is an authorized recovery mechanism that redelivers requests stored by Webhook Relay for the configured output. Receivers should still verify authenticity, reject unauthorized traffic and use idempotency controls to prevent repeated side effects.

Related

• Durable webhooks and automatic retries
• Forward webhooks to localhost
• Zero-retention buckets
• Outbound throttling