The endpoint URL
Every endpoint URL starts with your organization's slug, then the endpoint's:
https://in.webhookhq.dev/acme/acme-stripe-test
- It accepts any HTTP method:
POST,PUT,GETand the rest. - Anything after the URL is kept as the event's path and query. A webhook sent to
…/acme-stripe-test/webhooks/stripe?live=1is captured with the path/webhooks/stripeand the querylive=1, and forwarding adds them to the destination's URL. - The endpoint part is random (like
k3x9p2q7m4) unless you choose it. Choosing it, a custom slug, is on Developer and above: lowercase letters, numbers and dashes, likestripe-prod. Slugs only need to be unique within your organization. - Once the first webhook arrives, the URL is locked, since changing it would break the senders already using it. You can still rename the endpoint. For a different URL, create a new endpoint.
Create endpoints with New endpoint in a workspace. Free has 3 endpoints, Developer 5, and Pro and above unlimited. A random slug is harder to guess than a custom one, so pair custom slugs with a signature check or a secret header.
Require a secret header
Endpoints are open by default: anyone with the URL can send to them, which is what most providers expect. If the sender can add a header, you can require one carrying a secret. This works on every plan.
- On the endpoint's page, click Settings, then find Authentication.
- Keep the header as
Authorization(senders sendAuthorization: Bearer <secret>) or use your own, likeX-Api-Key. - Leave the secret empty to get a strong one, and click Require a secret header.
- Copy the secret: it's shown only once.
Requests without the right secret get 401 and aren't stored. The endpoint's page shows a Secret header tag and how many requests were refused in the last 24 hours. Generate a new secret replaces it (the old one stops working at once), and Make it open again removes it. In stored events, the header's value is masked.
Watch webhooks arrive
Keep the endpoint's page open: new webhooks appear in the list within about two seconds, with no refresh. Each row shows the event type (or the short id, like 3f9a2c1), method, path, size, sender and time. A coloured dot shows how its deliveries went, once you forward.
Click a webhook to see it in full:
- The method, path, sender, size, time and the sender's IP address. A Copy ID button copies the full id.
- Body: JSON and XML pretty-printed and as a collapsible tree, or the raw body exactly as sent.
- Headers, Query, and Form when the body is form data (Twilio's
MessageStatus=deliveredshows as a field).
Copy as cURL and Copy as fetch turn the webhook into a curl command or a JavaScript fetch call with its original headers and body:
curl -X POST https://in.webhookhq.dev/acme/acme-stripe-test/webhooks \
-H "Content-Type: application/json" \
-H "Stripe-Signature: t=1731900000,v1=5257a8..." \
-d '{"id": "evt_1Q...", "type": "invoice.paid", ...}'
Change the URL to http://localhost:3000/webhooks to run it against your own app. On plans that keep events longer than 30 days, older events load their body when you open them, a little more slowly.
Search and filter
Above the list:
- The search box takes ids, event types and paths (matched partly) and body text (matched exactly).
- A search starting with
$is a JSONPath condition on JSON bodies:$.type,$.data.object.customer == "cus_Q8x2LmN"or$.amount > 1000. - Filters for event type, sender, delivery status (Delivered, Failed, Sending; shown once the endpoint forwards) and time (last hour, 24 hours, 7 days, 30 days).
JSONPath and body conditions search the last 24 hours unless you pick a time. On plans that keep events longer than 30 days, searching inside bodies covers the last 30 days; older events are still found by id, type or path. Clear filters shows everything again.
Example: a customer says a renewal never went through. Pick invoice.payment_failed and Last 7 days, then search $.data.object.customer == "cus_Q8x2LmN".
On Pro and above, the Export menu downloads the list as CSV or JSON, following the filters, up to 50,000 events. An export that includes events older than 30 days is prepared in the background and emailed to you as a link that works for 7 days. The same search works from the terminal with whq events list (CLI) and through the API.
What senders get back
By default an endpoint answers 200 with an empty body, after the webhook is stored.
Verification handshakes are answered for you on every plan, with nothing to set up: Slack's url_verification challenge, Microsoft Graph's validationToken, Meta's (Facebook, Instagram, WhatsApp) and Strava's hub.challenge, Dropbox's challenge and Okta's verification header.
Custom responses (Pro and above) set what the endpoint sends back, under Response in the endpoint's settings:
- Status code (200 to 599), Headers and Body (up to 16 KB, sent as it is; set
Content-Typein the headers). - Delay (ms), up to 5 seconds, to see how a provider handles slow replies. Delays are best effort: at most 2 replies wait at once per endpoint and 3 per organization, none while WebhookHQ is busy, and none during a Team trial.
Example: Twilio expects TwiML back. Answer 200 with Content-Type: text/xml and <Response><Message>Thanks!</Message></Response>. Reset to default goes back to 200 with an empty body.
The request ID: every response, on every plan, carries X-WebhookHQ-Request-Id with a unique ID for that request. That includes custom responses, handshakes and refusals (a wrong secret header, over the plan's limit), and a custom response can't change or remove it. Providers such as Stripe show response headers in their delivery logs: copy the ID from there and quote it to support, who can follow that webhook through capture and every delivery attempt. If the sender includes its own X-Request-Id, it's noted alongside.
Instant bins
An instant bin is a capture URL without an account, for a quick look at a payload. Open webhookhq.dev/new and click Create a bin. The bin's page shows:
- the capture URL, like
https://in.webhookhq.dev/b/k3x9p2q7m4, to paste into the provider, - the viewer URL (
app.webhookhq.dev/bins/<id>), which opens in the same browser straight away, - the bin's token, shown only once. Other browsers ask for it before showing anything.
Webhooks appear live, as on an endpoint. A bin takes 100 webhooks a day (then 429 until the next day) and is deleted with its events after 7 days. Opening the capture URL in a browser sends the bin a GET and answers with a note pointing to the viewer URL.