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
| Field | Required | Rules |
|---|---|---|
destination_id | One of destination_id or target_url | A forward destination on the same endpoint. Disabled destinations are allowed |
target_url | One of destination_id or target_url | Must start with https:// |
extra_headers | No | An 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
}
}
| Field | Description |
|---|---|
replay_id | UUID of the replay record |
destination_id | The destination replayed to. Only present for destination replays |
destination_name | The destination’s name at replay time. Only present for destination replays |
status_code | HTTP status from the target, or null on connection failure |
response_time_ms | Round-trip time in milliseconds |
success | true if the target returned 2xx |
error | Connection-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 withx-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
| HTTP | Code | Cause |
|---|---|---|
| 400 | invalid_request | Both or neither of destination_id and target_url, or an extra_headers entry that breaks the rules above |
| 400 | bad_request | Invalid or non-HTTPS target_url, or a URL that isn’t allowed |
| 401 | unauthorized | Invalid API key |
| 403 | forbidden | The API key lacks the scope or permission to replay |
| 404 | not_found | Endpoint or request not found or not visible, or the destination isn’t on this endpoint |
| 409 | body_not_stored | The request’s body wasn’t stored because the organization reached its storage cap |
| 409 | body_unavailable | The 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
- Replay concept: when and why to replay
- Requests API: find request IDs to replay
- Destinations API: find destination IDs
- API keys: keys used for authentication