RudderStack webhooks
RudderStack webhooks are HTTP requests that its HTTP Webhook destination sends to your URL, carrying the events collected by the sources you connect to it.
These pages cover the HTTP Webhook destination, which sends RudderStack events to your endpoint. To send webhooks into RudderStack instead, use its Webhook Source. RudderStack's separate Webhook destination has its own settings and isn't covered here.
How RudderStack webhooks work
The destination gives a service with no ready-made RudderStack integration the same events your other tools receive, in cloud mode, so it doesn't have to query a warehouse for them. Your settings decide what arrives: POST by default, or PUT, PATCH, GET or DELETE, with a JSON, XML or form body. Batching, for JSON only, sends an array of up to 100 events when the batch fills or after 5 seconds.
With Send the event payload as is, which is on by default, the body is the RudderStack event. Its type is the call type, such as track or identify, and on a track call event holds the action name your team chose, so those names have no fixed list. Turn that setting off and only the fields you map are sent, so type may be missing. RudderStack adds no event-type header, and nothing versions the format.
Key facts
The type field in the default body; mappings can drop it JSON Content type: application/json, application/xml, application/x-www-form-urlencoded.
anonymousId, channel, context, event, integrations, messageId, properties, originalTimestamp, type, sentAt Setting up RudderStack webhooks
- In the RudderStack dashboard, add a source, select HTTP Webhook from the destinations and set the Base URL. An
httpsURL needs a valid TLS certificate. - Under Authentication, choose Basic Auth and enter a username and password. Leave Send the event payload as is on unless you need a mapping.
- Rudder CLI rejects
localhostandngrok.ioaddresses, so for local work usehookdeck listen 3000 rudderstack --path /webhooks/rudderstack, which gives you a public URL. RudderStack's Event Playground sends sample events. - The destination's Live Events tab shows failures and each Error Response. To resend failed events, ask RudderStack Support about Event Replay, available on Growth (up to 7 days) and Enterprise (up to 30 days).
Delivery behaviour
not documented RudderStack publishes no request timeout; respond quickly Retries 3 hours for 5XX and 429, with exponential backoff, at least 3 times After retries run out aborted and any other 4XX aborts at once, with no retries Ordering per user a failing event holds that user's later events until it's sent or aborted Known failure modes
From Hookdeck's RudderStack guide →-
A 4XX from your endpoint aborts the event
RudderStack aborts an event on a
Retries and aborted events →4XXwithout retrying it, so a bad deploy that returns404or a password change that returns401drops events. Return503for problems you expect to clear, because5XXand429are retried for 3 hours. -
One failing event holds back a user's later events
While an event is failing, RudderStack doesn't send that user's later events until it's delivered or aborted. If you'll never be able to process an event, log it and return a
Ordering per user →2xxso it doesn't hold up the rest. -
Retries can repeat events
A request that failed after your handler did some of its work is sent again. Deduplicate on
Handle duplicates →messageId, and map it into the body if you don't send the event as is. -
A settings change alters every request
Turning on batching, adding a mapping or changing the body format changes what your endpoint receives, and nothing in the request says so. Accept an object or an array, and keep
Telling events apart →typein any mapping.
RudderStack webhook best practices
- Choose your status codes.
RudderStack retries
5XXand429and aborts on any other4XX. Return503for a problem you expect to clear. - Deduplicate on
messageId. The SDKs keep it unchanged across retries. If you use a mapping, map it too. - Order by
timestamp. RudderStack corrects it for client clock skew, and saysreceivedAtdoesn't preserve chronological order. - Accept an object or an array. Turning on batching changes the body to an array, so handle both and process each event on its own.
- Acknowledge before you process.
RudderStack publishes no timeout, so authenticate, store the request and return
200, then work from a queue.
Common RudderStack webhook events
User activity
track | A user action is recorded under a name you choose |
page | A user views a web page |
screen | A user views a mobile app screen |
Identity
identify | A user is identified, with their traits |
group | A user is associated with a group |
alias | Two identities of one user are merged |
Events
| Resource | Events | Payloads |
|---|---|---|
RudderStack events | 7 | 1 |
In this hub
| Webhook events → | Every covered RudderStack event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to RudderStack events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems, such as timeouts and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill rudderstack-webhooks |
Keep a 4XX from losing your RudderStack events.
Event Gateway checks the Basic credentials, stores each request as it arrives and delivers it to your service with retries you control, so a failure on your side doesn't abort the event in RudderStack.