HookDeploy

The Replay API re-sends a captured request to a target URL you specify, using the original method, headers, query string, and body.

Replay a request

POST /v1/endpoints/:id/requests/:requestId/replay
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"}'

Body fields:

FieldRequiredRules
target_urlyesmust start with https://

Response

Success (target returned 2xx):

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

Connection failure:

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

Target returned non-2xx:

{
  "data": {
    "status_code": 500,
    "response_time_ms": 89,
    "success": false,
    "error": null
  }
}
FieldDescription
status_codeHTTP status from target, or null on connection failure
response_time_msRound-trip time in milliseconds
successtrue if target returned 2xx
errorConnection-level error message, or null

What gets sent

HookDeploy fetches the original body from R2 via the ingestion Worker’s internal payload endpoint, then sends:

  • Original HTTP method
  • Original headers (minus Cloudflare/proxy headers)
  • Original query string
  • Original body bytes

Plus diagnostic headers:

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

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

Permissions

Replay requires the requests.replay permission on the API key’s organization. Granted to: super admin, admin, developer, and viewer.

Recording

Every replay is recorded in the replays table with target URL, status, timing, and timestamp. Replays do not count toward monthly webhook ingestion limits.

Error responses

HTTPCodeCause
400bad_requestMissing target_url, invalid URL, or non-HTTPS target
401unauthorizedInvalid API key
404not_foundEndpoint or request ID not found
429rate_limitedAPI rate limit exceeded

Example: replay to ngrok

# 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://abc123.ngrok.io/webhooks/stripe"}'

Replay vs forwarding

This API triggers a manual replay — one request, one target, on demand. It is not the same as auto-forwarding, which proxies every incoming webhook to a fixed URL automatically.

Next steps