Skip to content

Docs / Guides

Forwarding

Forwarding sends every webhook an endpoint captures on to your own servers, retries the ones that fail, and shows every attempt, so you can see exactly what your server received and answered.

Add a destination

  1. On the endpoint's page, click Settings and find Forwarding.
  2. Enter the Destination URL, like https://api.acme.dev/webhooks/stripe, and optionally a Name ("Billing API").
  3. Add any headers your server needs, then click Start forwarding.

From then on, every new webhook is sent there. Webhooks captured before you added the destination aren't sent; replay them if you need them.

Fan-out: add more destinations with Add destination, and each webhook goes to all of them. If one is down, the others still get every event, and each has its own delivery history.

Plan Destinations per endpoint
Free, Developer 1
Pro 5
Team 10
Scale 25
Enterprise Unlimited

Edit changes a destination's URL, name or headers for new deliveries. Remove stops forwarding to it and cancels the webhooks still waiting to be sent there.

What your server receives

Each delivery keeps the sender's method, headers and body, so your signature check works as it would with the provider.

  • The path is added. Anything after the endpoint URL is added to the destination's URL. With the destination https://api.acme.dev/hooks, a webhook sent to in.webhookhq.dev/acme/acme-stripe-test/stripe?live=1 arrives at https://api.acme.dev/hooks/stripe?live=1.
  • Destination headers are added to every request and replace the sender's header of the same name. Use them for credentials, like Authorization: Bearer sk_live_…. They're stored encrypted, as are credentials in the URL (https://user:password@…, ?token=…).
  • Idempotency-Key stays the same across every retry of a delivery, so your server can safely ignore a repeat. If the sender already sent an Idempotency-Key, theirs is kept.
  • WebhookHQ's own headers: X-WebhookHQ-Event-Id, X-WebhookHQ-Delivery-Id and X-WebhookHQ-Attempt (1 for the first try).

Any 2xx answer counts as delivered. Redirects aren't followed, and WebhookHQ waits up to 10 seconds for an answer before counting the attempt as a timeout.

Retries

When your server answers with an error, can't be reached or times out, WebhookHQ tries again after 30 seconds, 5 minutes and 30 minutes. If your server answers 429 or 503 with a Retry-After header, the next try waits at least that long.

Example: your API is down for 20 minutes during a deploy. Webhooks that arrived in that window are tried again on the schedule and succeed once it's back, without anyone stepping in.

After the last retry fails, the delivery is marked Failed. To try it once more, open the event and click Send again on that delivery.

Paused destinations

A destination that fails continuously for an hour is paused, so retries don't pile up while it's down:

  • New webhooks for it wait, untried. Their deliveries show Waiting.
  • The organization's owners and admins and the workspace's managers get an email saying so ("Deliveries to analytics.acme.dev are paused"), with a link to resume.
  • The endpoint's settings show the destination as Paused. A destination that's failing but not yet paused shows Failing.

Fix your server, then click Resume on the destination. The webhooks that waited are sent first, and everyone who got the first email gets another saying it's resumed.

The delivery timeline

Open any event to see its deliveries, one per destination, each with its state:

State Means
Sending Being sent now
Delivered Your server answered 2xx, with the status and how long it took
Retrying The last attempt failed; shows the next try's time
Waiting The destination is paused
Failed Gave up after all its attempts
Held Arrived over the plan's monthly events (below)
Cancelled Not sent: the destination was removed

Expand a delivery to see every attempt in order: its number, when it was sent, the result (status code or error) and how long it took, then the latest response body (its first 16 KB).

Example: an order email arrived five minutes late. The timeline shows a 502 at 14:02:00, a timeout on the retry at 14:02:30, and success at 14:07:30.

The event list's delivery filter (Delivered, Failed, Sending) finds the failures. whq events list --status failed does the same from the CLI.

Over the monthly limit

Webhooks that arrive past your plan's monthly events are still stored and answered, but they're hidden and their deliveries are Held. Upgrading (or, on Team and Scale, turning on extra events) shows them again, and an owner chooses on the Usage page whether to send the held deliveries or dismiss them. Details in Plans and limits.

Public servers only

Destinations must be public servers: private, local and cloud metadata addresses are refused. To get webhooks on your own machine, use the CLI:

whq listen 3000 --endpoint acme-stripe-test

Every webhook goes to http://localhost:3000 as well as to your destinations, and shows in the event's deliveries as Tunnel · . Tunnel deliveries are tried once; replay to try again. See the CLI reference.