# 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](https://www.rudderstack.com/docs/sources/event-streams/cloud-apps/webhook-source/). RudderStack's separate [Webhook destination](https://www.rudderstack.com/docs/destinations/webhooks/) has its own settings and isn't covered here.

Agent skill: `npx skills add hookdeck/webhook-skills --skill rudderstack-webhooks` ([details](https://hookdeck.com/webhooks/rudderstack/skill))

> Independent reference generated from hookdeck/webhook-registry (commit ff7f882, 20 Nov 2026). [RudderStack's official docs](https://www.rudderstack.com/docs/destinations/http-webhook/setup-guide/).

[Overview](https://hookdeck.com/webhooks/rudderstack) · [Webhook events (7)](https://hookdeck.com/webhooks/rudderstack/events) · [MCP events](https://hookdeck.com/webhooks/rudderstack/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/rudderstack/verify) · [Production guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/rudderstack/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `None (unsigned)` | [RudderStack docs](https://www.rudderstack.com/docs/destinations/http-webhook/setup-guide/) |
| How events are identified | `The type field in the default body; mappings can drop it` | [RudderStack docs](https://www.rudderstack.com/docs/event-spec/standard-events/common-fields/) |
| Body format | `JSON` Content type: application/json, application/xml, application/x-www-form-urlencoded. | [RudderStack docs](https://www.rudderstack.com/docs/rudder-cli/destination-types/http-webhook/) |
| Other headers | `user-agent, content-type` | [RudderStack docs](https://www.rudderstack.com/docs/destinations/http-webhook/setup-guide/) |
| Envelope | `anonymousId, channel, context, event, integrations, messageId, properties, originalTimestamp, type, sentAt` | [RudderStack docs](https://www.rudderstack.com/docs/destinations/http-webhook/setup-guide/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill rudderstack-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/rudderstack/skill) |

[Verify RudderStack webhooks](https://hookdeck.com/webhooks/rudderstack/verify)

## 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.

## 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

- **Timeout:** not documented. RudderStack publishes no request timeout; respond quickly. [Guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** 3 hours. for `5XX` and `429`, with exponential backoff, at least 3 times. [Guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries run out:** aborted. and any other `4XX` aborts at once, with no retries. [Guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** per user. a failing event holds that user's later events until it's sent or aborted. [Guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

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](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#ordering)
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](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#choosing-events)

From [Hookdeck's RudderStack guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts).

## RudderStack webhook best practices

- **[Choose your status codes](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#retries).** RudderStack retries `5XX` and `429` and aborts on any other `4XX`. Return `503` for a problem you expect to clear.
- **[Deduplicate on `messageId`](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#duplicates).** The SDKs keep it unchanged across retries. If you use a mapping, map it too.
- **[Order by `timestamp`](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#ordering).** RudderStack corrects it for client clock skew, and says `receivedAt` doesn't preserve chronological order.
- **[Accept an object or an array](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#choosing-events).** Turning on batching changes the body to an array, so handle both and process each event on its own.
- **[Acknowledge before you process](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts#timeouts).** RudderStack publishes no timeout, so authenticate, store the request and return `200`, then work from a queue.

## Common RudderStack webhook events

### User activity

- [track](https://hookdeck.com/webhooks/rudderstack/events#track): A user action is recorded under a name you choose
- [page](https://hookdeck.com/webhooks/rudderstack/events#page): A user views a web page
- [screen](https://hookdeck.com/webhooks/rudderstack/events#screen): A user views a mobile app screen

### Identity

- [identify](https://hookdeck.com/webhooks/rudderstack/events#identify): A user is identified, with their traits
- [group](https://hookdeck.com/webhooks/rudderstack/events#group): A user is associated with a group
- [alias](https://hookdeck.com/webhooks/rudderstack/events#alias): Two identities of one user are merged

## Events

| Resource | Events | Payloads |
|---|---|---|
| [RudderStack events](https://hookdeck.com/webhooks/rudderstack/events#resource-other) | 7 | 1 |

[All 7 events](https://hookdeck.com/webhooks/rudderstack/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/rudderstack/events): Every covered RudderStack event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/rudderstack/mcp-events): How an agent subscribes to RudderStack events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/rudderstack/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/rudderstack/guide-duplicates-ordering-retries-timeouts): Production problems, such as timeouts and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/rudderstack/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill rudderstack-webhooks`
---

Not affiliated with RudderStack. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/rudderstack.json) · [Report a correction](https://hookdeck.com/contact)
