Skip to content
HookDeploy
HookDeployDocumentation
On this page ↓
Getting startedIntroduction

What HookDeploy is, who it's for, and the core concepts behind webhook capture and replay.

→Getting startedQuickstart

From signup to your first captured webhook in under five minutes.

→Getting startedYour first endpoint

Create an endpoint, copy its URL, send test requests, and read the request inspector.

→Core conceptsForwarding

Forward captured webhooks to one or more destinations, with optional payload transformation.

→Core conceptsTransformations

Reshape webhook payloads before forwarding with the visual editor and 23 built-in formatters.

→Core conceptsEndpoint security

Restrict access to your HookDeploy endpoints with IP allowlists and secret token authentication.

→Core conceptsCustom Responses

Override the HTTP response HookDeploy returns to webhook senders. Set a custom status code, response body, and dynamic variables for testing and mocking.

→Core conceptsResponse Delay

Add an artificial delay before HookDeploy responds to a webhook sender. Useful for testing timeout handling and retry logic.

→
↑↓ navigateEnter openEsc close

Replay API

Re-send a captured webhook to any HTTPS target URL via the REST API.

The Replay API re-sends the stored captured representation to a target URL you specify.

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": {
    "replay_id": "uuid",
    "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"
  }
}

Target returned non-2xx:

{
  "data": {
    "replay_id": "uuid",
    "status_code": 500,
    "response_time_ms": 89,
    "success": false,
    "error": null
  }
}
FieldDescription
replay_idUUID of the replay record for audit trail
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

Stored payloads are decrypted for authorized replay. HookDeploy sends:

  • Captured HTTP method
  • Stored headers (minus proxy headers)
  • Captured query string
  • Stored body

Sanitization may mean the stored representation differs from the byte-for-byte unsanitized request originally received.

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 with target URL, status, timing, and timestamp. Replays do not count toward monthly webhook ingestion usage.

Error responses

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

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://dev-tunnel.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