Skip to content
HookDeploy
On this page ↓

Replay

Re-send a captured webhook to one of your forward destinations or to any HTTPS URL, with one-time headers and replay history.

Replay re-sends a captured request on demand. Send it to one of the endpoint’s forward destinations, with that destination’s headers and transformation applied, or to any HTTPS URL, such as your local dev server through a tunnel.

When to use replay

  • A forward failed, and your server is fixed now
  • Your local server wasn’t running when the webhook arrived
  • You need to test the same payload multiple times
  • A teammate captured a webhook and you want to process it locally

Replay is on-demand. Unlike forwarding, nothing is re-sent unless you trigger it. To re-send many failed deliveries at once, use incident bulk replay.

Choose a target

A forward destination

Pick any destination on the request’s endpoint. The replay goes through the same delivery path as a live forward, so it gets:

  • the destination’s injected headers
  • its current transformation
  • its method override and header stripping
  • agent delivery, for destinations that deliver to a HookDeploy Agent

Disabled destinations can be selected too, so you can test a paused destination before switching it back on.

Use this when you’re re-delivering to your own systems. The request arrives the way a forward would, including any authentication header the destination adds.

A custom URL

Enter any HTTPS URL. HookDeploy sends the request as it was captured: destination headers and transformations aren’t applied. Use this for one-off targets, like a local handler behind ngrok or Cloudflare Tunnel.

What gets sent

HookDeploy loads the stored copy of the request and sends:

  • the captured method
  • the stored headers, minus proxy headers
  • the captured query parameters, except the endpoint token
  • the stored body

Plus these headers:

x-hookdeploy-replay: 1
x-hookdeploy-original-request-id: {request-id}

Replays to a destination also get that destination’s headers and transformation, as described above.

A replay can differ from the original request:

  • Redacted headers are left out. Headers that were redacted when the request was stored, such as Authorization, aren’t sent. Supply them with one-time headers, or replay to a destination that injects them.
  • Privacy filters apply. If privacy filters or body key sanitization changed what was stored, the replay sends the stored version.
  • Missing bodies can’t be replayed. If a request’s body wasn’t stored, because your organization reached its storage cap, the request can’t be replayed.

Your target can detect replays with the x-hookdeploy-replay header and skip side effects when needed, for example so a customer isn’t charged twice.

One-time headers

Add up to 20 headers to a single replay: for example, an Authorization header that was redacted, or an API key that has since been rotated. One-time headers:

  • apply to that replay only, with either kind of target
  • replace any stored or destination header with the same name, ignoring case
  • are never saved. Their values aren’t stored, logged, or shown in history. Replay history lists header names only.

These headers can’t be set: Host, Content-Length, Transfer-Encoding, Connection, and any header that starts with x-hookdeploy-. Each value can be up to 4 KB, and all values together up to 16 KB.

Replay from the dashboard

  1. Open an endpoint and click a request in the stream.
  2. Click Replay.
  3. Choose a destination, or choose Custom URL and enter an HTTPS URL.
  4. Optionally, open Add headers for this replay and add one-time headers.
  5. Click Send replay.

The result panel shows the HTTP status, response time, and any error.

Replay via the API

Send a destination_id or a target_url, with optional extra_headers:

curl -s -X POST \
  "https://api.hookdeploy.dev/v1/endpoints/ENDPOINT_ID/requests/REQUEST_ID/replay" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_id": "DESTINATION_ID"}'

See the Replay API for every field, response, and error.

Permissions

Replaying requires the requests.replay permission, which super admins, admins, and developers have, and you must be able to see the request’s endpoint. API keys also need the requests:replay scope.

Replay history

Every replay is recorded with its target (the destination’s name, or the URL), status, timing, and timestamp, plus the names of any one-time headers. If a destination is deleted later, history keeps its name and marks it as deleted. Replay history is on the request detail page.

There’s no limit on replays per request. Replays don’t count toward your monthly request allowance, which applies to incoming webhooks only.

Custom URL requirements

  • Must start with https://
  • Must be reachable from HookDeploy over the public internet
  • localhost URLs won’t work directly. Use a tunnel such as ngrok or Cloudflare Tunnel, or replay to a destination that delivers to a HookDeploy Agent

Replay vs forwarding

ForwardingReplay
TriggerAutomatic, on every webhookManual, one request at a time
TargetThe endpoint’s destinationsA destination you pick, or any HTTPS URL
SendsThe original requestThe stored copy of the request
Adds replay headersNoYes
Use caseContinuous deliveryRecover a failed delivery, or debug an event

Security note

A replay sends the stored copy of the request, which can contain sensitive data. Only replay to custom URLs you trust.

Next steps