Add a destination
- On the endpoint's page, click Settings and find Forwarding.
- Enter the Destination URL, like
https://api.acme.dev/webhooks/stripe, and optionally a Name ("Billing API"). - 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 toin.webhookhq.dev/acme/acme-stripe-test/stripe?live=1arrives athttps://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-Keystays the same across every retry of a delivery, so your server can safely ignore a repeat. If the sender already sent anIdempotency-Key, theirs is kept.- WebhookHQ's own headers:
X-WebhookHQ-Event-Id,X-WebhookHQ-Delivery-IdandX-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.