Skip to content
HookDeploy
On this page ↓

Replay API

Re-send a captured webhook to a forward destination or any HTTPS URL via the REST API, with optional one-time headers.

The Replay API re-sends the stored copy of a captured request to one of its endpoint’s forward destinations, or to an HTTPS URL you specify.

Replay a request

POST /v1/endpoints/:id/requests/:requestId/replay

Replay to a destination, with its injected headers and transformation:

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"}'

Replay to a custom URL, with a one-time header:

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 '{
    "target_url": "https://example.com/webhooks/replay",
    "extra_headers": { "Authorization": "Bearer YOUR_HANDLER_SECRET" }
  }'

Body fields

FieldRequiredRules
destination_idOne of destination_id or target_urlA forward destination on the same endpoint. Disabled destinations are allowed
target_urlOne of destination_id or target_urlMust start with https://
extra_headersNoAn object of header names to values, used for this replay only. See One-time headers

Send exactly one of destination_id and target_url.

Response

Success (the target returned 2xx):

{
  "data": {
    "replay_id": "uuid",
    "status_code": 200,
    "response_time_ms": 142,
    "success": true,
    "error": null
  }
}

Replays to a destination also include the destination:

{
  "data": {
    "replay_id": "uuid",
    "destination_id": "uuid",
    "destination_name": "Production server",
    "status_code": 200,
    "response_time_ms": 142,
    "success": true,
    "error": null
  }
}

Connection failure:

{
  "data": {
    "replay_id": "uuid",
    "status_code": null,
    "response_time_ms": 312,
    "success": false,
    "error": "Connection refused"
  }
}

The target returned a non-2xx status:

{
  "data": {
    "replay_id": "uuid",
    "status_code": 500,
    "response_time_ms": 89,
    "success": false,
    "error": null
  }
}
FieldDescription
replay_idUUID of the replay record
destination_idThe destination replayed to. Only present for destination replays
destination_nameThe destination’s name at replay time. Only present for destination replays
status_codeHTTP status from the target, or null on connection failure
response_time_msRound-trip time in milliseconds
successtrue if the target returned 2xx
errorConnection-level error message, or null

What gets sent

HookDeploy decrypts the stored copy of the request and sends:

  • the captured HTTP 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 the destination’s injected headers, current transformation, method override, and header stripping, and are delivered through a HookDeploy Agent when the destination uses one. Replays to a target_url are sent as captured, without destination settings.

Headers that were redacted in storage, such as Authorization, aren’t sent. If privacy filters or body key sanitization changed the stored copy, the replay sends the stored version.

Your target can skip duplicate processing when x-hookdeploy-replay: 1 is present.

One-time headers

extra_headers adds headers to this replay only. They replace any stored or destination header with the same name, ignoring case. Their values are never stored or logged, and replay history records header names only.

  • Up to 20 headers
  • Header names must be valid HTTP header names
  • Values can’t contain line breaks, and can be up to 4 KB each and 16 KB in total
  • These can’t be set: Host, Content-Length, Transfer-Encoding, Connection, and any header that starts with x-hookdeploy-

Error messages name the header that failed, never its value.

Permissions

Replay requires the requests:replay scope on the API key, and the requests.replay permission for the user who created the key. Super admins, admins, and developers have that permission. The key’s user must also be able to see the request’s endpoint.

Recording

Every replay is recorded with its target (the destination, or the URL), status, timing, timestamp, and the names of any one-time headers. Replays don’t count toward monthly webhook ingestion usage.

Error responses

HTTPCodeCause
400invalid_requestBoth or neither of destination_id and target_url, or an extra_headers entry that breaks the rules above
400bad_requestInvalid or non-HTTPS target_url, or a URL that isn’t allowed
401unauthorizedInvalid API key
403forbiddenThe API key lacks the scope or permission to replay
404not_foundEndpoint or request not found or not visible, or the destination isn’t on this endpoint
409body_not_storedThe request’s body wasn’t stored because the organization reached its storage cap
409body_unavailableThe request’s body isn’t available

Example: replay to a tunnel

# 1. List recent requests to find an ID
curl -s "https://api.hookdeploy.dev/v1/endpoints/ENDPOINT_ID/requests?limit=1" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

# 2. Replay the most recent request to your local tunnel
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 '{"target_url": "https://dev-tunnel.ngrok.io/webhooks/stripe"}'

Replay vs forwarding

This API triggers a manual replay: one request, one target, on demand. Forwarding sends every incoming webhook to the endpoint’s destinations automatically. To re-send many failed deliveries at once, use incident replay.

Next steps