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.

7 events covered

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

Signature header
None (unsigned)
How events are identified
The type field in the default body; mappings can drop it
Body format
JSON

Content type: application/json, application/xml, application/x-www-form-urlencoded.

Other headers
user-agent, content-type
Envelope
anonymousId, channel, context, event, integrations, messageId, properties, originalTimestamp, type, sentAt
Agent skill
npx skills add hookdeck/webhook-skills --skill rudderstack-webhooks

Verify RudderStack webhooks →

Setting up RudderStack webhooks

  • In the RudderStack dashboard, add a source, select HTTP Webhook from the destinations and set the Base URL. An https URL 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 localhost and ngrok.io addresses, so for local work use hookdeck 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

  1. A 4XX from your endpoint aborts the event

    RudderStack aborts an event on a 4XX without retrying it, so a bad deploy that returns 404 or a password change that returns 401 drops events. Return 503 for problems you expect to clear, because 5XX and 429 are retried for 3 hours.

    Retries and aborted events →
  2. 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 2xx so it doesn't hold up the rest.

    Ordering per user →
  3. Retries can repeat events

    A request that failed after your handler did some of its work is sent again. Deduplicate on messageId, and map it into the body if you don't send the event as is.

    Handle duplicates →
  4. 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 type in any mapping.

    Telling events apart →

RudderStack webhook best practices

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

alias · group · identify · page +3

7 1

All 7 events →

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.

Not affiliated with RudderStack. Facts are compiled from public sources and linked inline.