Skip to content
HookDeploy
On this page ↓

Forwarding

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

HookDeploy can automatically forward every captured webhook to one or more destination URLs. Use forwarding to proxy webhooks to your production server, notify multiple services simultaneously, or transform payloads before they reach your infrastructure.

How forwarding works

When a webhook arrives at your HookDeploy endpoint:

  1. The payload is captured for storage (optional privacy filters run before write; fail-closed if they error)
  2. HookDeploy forwards the original request body to each enabled destination in parallel (plus any per-destination transformation)
  3. Forward results (status code, response time, errors) are recorded per destination
  4. Your dashboard shows the forward status next to each captured request

Once a webhook is captured, HookDeploy responds to the sender right away with 200 OK, or with your custom response if you’ve configured one. The sender never waits for forwarding to complete. Requests rejected before capture, for example by endpoint security or a plan limit, receive an error status instead.

Multiple destinations

Each endpoint supports multiple named forward destinations. Examples:

  • Production server — your real webhook handler
  • Slack alerts — a Slack incoming webhook URL for team notifications
  • CRM — your CRM’s webhook endpoint for customer event tracking
  • Analytics — a data pipeline ingestion endpoint

All destinations receive the webhook in parallel. If one destination fails, the others are unaffected.

Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Destination configuration

Each destination has:

  • Name — a label for your team (“Production server”, “Slack alerts”)
  • URL — must be HTTPS
  • Method override — optionally change the HTTP method (e.g. POST → PUT)
  • Header injection — add authentication headers your server requires
  • Payload transformation — modify the payload before forwarding
  • Enabled toggle — pause a single destination without affecting others

Configure destinations on your endpoint’s Forwarding tab.

Header injection

Add headers to every forwarded request. The most common use case is authentication:

Authorization: Bearer your-server-token
X-Tenant-ID: acme-corp

Injected headers override matching headers from the original request. HookDeploy always adds these headers and they cannot be overridden:

  • x-hookdeploy-forward: 1
  • x-hookdeploy-destination: {destination name}
  • x-hookdeploy-request-id: {request id}

Availability is plan-controlled. Check the current dashboard or pricing page for the features enabled for your organization.

Payload transformation

Transform the webhook payload before it reaches your destination. Use the visual editor to:

  • Strip PII — remove sensitive fields like customer emails before forwarding to analytics
  • Rename fields — map data.amount to payment.amount to match your server’s schema
  • Format values — convert cents with cents_to_currency, mask emails, format dates, and more
  • Conditions — run a rule only when another field matches (for example only in livemode)
  • Combine fields — join multiple paths into one string
  • Form-encoded bodies — transform Twilio/Slack-style posts; choose JSON or keep original wire format per destination
  • Add static fields — inject {"source": "stripe", "version": "2"} into every payload
  • Allowlist fields — forward only specific fields, drop everything else

See Transformations for the full formatter reference, limits, and recipes. To redact storage without changing destinations, see Privacy filters.

Transformation availability is plan-controlled: forwarding transforms are on Starter and above.

Transformation modes

Passthrough mode (default): All fields are forwarded. Apply transforms to specific fields only. Use this when you want to forward most of the payload and only modify a few fields.

Allowlist mode: Only fields you explicitly select are forwarded. Nested paths keep their structure unless you rename them. Use this for strict PII control — nothing gets through unless you approve it.

Available formatters (examples)

FormatterInputOutput
cents_to_currency (USD)4200"42.00"
unix_to_iso1716912060"2024-05-28T14:01:00.000Z"
mask"john@example.com""joh*************"
hash"john@example.com"SHA-256 hex digest
uppercase"hello""HELLO"
prefix"123""order_123"
set_nullanynull
…35 formatters total

Full formatter reference in Transformations.

Forward result tracking

Every forward attempt is recorded. In the request detail view, you can see:

  • Which destinations received the webhook
  • HTTP status code from each destination
  • Response time in milliseconds
  • Error message if the forward failed
  • Whether a transformation was applied

Destination response body capture

On Starter and above, you can opt in per forward destination to capture the destination’s HTTP response body (not just status code and response time). Enable Log response body on the destination in the dashboard.

Captured response bodies are encrypted at rest with the same per-organization keys as request payloads. They follow the same retention policy as captured requests and are purged when the parent request expires.

Retrieve captured bodies from the dashboard request detail view, or via the Requests API (GET .../forward-results/:forwardResultId/response). This applies to standard HTTPS URL destinations; tunnel-based destinations are not supported for response body capture today.

What gets forwarded

By default (no destination transformation configured), HookDeploy forwards from the original inbound request, not from the privacy-filtered storage copy:

  • The captured HTTP method (or your override)
  • Captured headers, excluding proxy headers
  • Your injected headers, which replace any original header with the same name
  • The original request body (then any per-destination transformation)
  • Captured query parameters, except the endpoint token

Plus HookDeploy adds:

  • x-hookdeploy-forward: 1
  • x-hookdeploy-destination: {destination name}
  • x-hookdeploy-request-id: {request id}

Privacy filters affect storage only.

Retry behavior

HookDeploy retries a failed forward when the destination returns a 5xx status or 429, or can’t be reached. Other 4xx responses are treated as final and aren’t retried. Each attempt times out after 15 seconds by default. Retry delays are measured from the previous failure.

PlanMax retriesSchedule
Free0No automatic retries
Starter330 seconds, 5 minutes, 30 minutes
Pro and Scale5Choose a preset. Standard: 30 seconds, 5 minutes, 30 minutes, 1 hour, 2 hours
Enterprise10Configured per destination

On Pro and Scale, intelligent retry waits for a destination’s rate-limit reset when a 429 response says it’s longer than the scheduled delay, up to 24 hours.

Destinations that deliver to a production agent retry retryable failures even when retries are turned off. Development agents never retry.

Retries and signature verification

Retries and replays re-send the provider’s original signature headers. Many providers only accept a signature for a short time after signing it: Stripe’s libraries default to 5 minutes, and Paddle’s SDKs to 5 seconds. A retry or replay that arrives after that window fails verification in your handler, even though the signature is genuine.

Retries and replays also send the stored copy of the request. Headers redacted in storage, such as Authorization, are left out. If privacy filters or body key sanitization changed the stored body, the provider’s signature won’t match. If the body wasn’t stored because your organization reached its storage cap, the request can’t be retried or replayed.

For providers with short signature windows, treat the webhook as a notification: verify it, and if only the timestamp check fails, take the event ID from the payload and fetch the event from the provider’s API.

You can also replay any captured request manually, to one of its destinations or to any HTTPS URL.

Next steps