Webhook events and payloads

This page answers one question: what will hit my endpoint? Each delivery is an HTTP POST from Brudcast to your URL, with a JSON envelope whose data object depends on the event type. You choose the types under Subscribe to events in Developers > Webhooks, or in the events array on the platform API (https://core-service.prod.brudcast.com/api/v1/user, scope webhooks:write).

Brudcast currently sends deliveries for push.token_invalidated and test.event only. You can subscribe to the other event types, but no deliveries are sent for them. Don’t build a workflow that waits for one. Use the API calls under Events that aren’t delivered instead.

Headers

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Signature`	Lowercase hex HMAC-SHA256 of the raw body, keyed with the endpoint’s secret. No prefix. See Verify signatures
`X-Webhook-Delivery-Id`	The delivery’s ID. The same value as `delivery_id` in the body
`X-Webhook-Event`	The event type. The same value as `event` in the body
Your custom headers	Each header you configured on the endpoint. A custom header with the same name as one above replaces it

HTTP header names aren’t case-sensitive. Many frameworks give them to you in lowercase, for example x-webhook-signature.

Envelope

Every event, whatever its type, arrives in the same four fields.

string

required

The delivery’s ID, a UUID. It stays the same across automatic retries and manual resends. Use it to skip deliveries you’ve already processed.

string

required

The event type, for example push.token_invalidated.

object

required

The event’s data. Its fields are listed per event below.

integer

required

Unix time, in seconds, when Brudcast recorded the delivery. This isn’t the time of the current attempt: retries and manual resends carry the original value.

The body Brudcast sends is compact JSON, with no spaces or line breaks. The examples on this page are formatted to make them easier to read. Always verify the signature against the bytes you received, not against JSON you’ve parsed and serialized again.

Delivered events

These two are the only event types Brudcast sends today.

`push.token_invalidated`

Firebase Cloud Messaging reported a device token as no longer registered, as registered to a different Firebase project, or as malformed. Brudcast expires the device so campaigns stop addressing it, then sends this event. It fires once per device: a later report about a device that’s already expired sends nothing.

string

required

The ID of the device record on the contact. It matches the id of one entry in the contact’s pushNotifications array.

string

required

The contact the device belongs to.

string

required

The push application the token was registered with.

string

required

The device platform: ios, android or web.

string | null

required

The reason Firebase gave, as text. The wording comes from Firebase and can vary, so don’t match on it.

string | null

required

When the token was rejected, as an ISO 8601 timestamp.

{
  "delivery_id": "01a08ff7-2a11-7d52-8e03-5b7c9d0e4f12",
  "event": "push.token_invalidated",
  "data": {
    "tokenId": "01a08b3c-5e21-7f40-8a62-3d9e1c7b4a05",
    "contactId": "01a07d2e-9b14-7c83-b5f1-0e6a2d8c4f37",
    "applicationId": "01a05f61-3c7d-7e29-9f08-4b1a6e2d7c93",
    "platform": "android",
    "reason": "Requested entity was not found.",
    "occurredAt": "2026-09-11T10:15:29.874Z"
  },
  "timestamp": 1789121730
}

A typical handler looks up the device by tokenId and stops sending to it from your own systems too. For example, it deletes the token from your user’s profile so the app registers a fresh one on its next launch.

`test.event`

You selected Test Webhook on the endpoint, or called POST /webhook-endpoints/{id}/test. It goes to that endpoint only. It’s sent whether or not the endpoint subscribes to test.event, and even while the endpoint is disabled.

string

required

Always This is a test webhook delivery.

string

required

When the test was requested, as an ISO 8601 timestamp. Unlike the envelope’s timestamp, this one is a string.

{
  "delivery_id": "01a08ff7-17d0-7c3e-9b41-2c8f5e7d1a90",
  "event": "test.event",
  "data": {
    "message": "This is a test webhook delivery",
    "timestamp": "2026-09-11T10:15:30.512Z"
  },
  "timestamp": 1789121730
}

Because test.event reaches any endpoint on demand, it’s the way to prove your URL, signature check and delivery_id handling work before you rely on them.

Events that aren’t delivered

The dashboard lists these, and the API accepts them in events, but Brudcast doesn’t send deliveries for them, so they have no payload to document. The right-hand column gives the public API call that answers the same question.

Group	Event types	Use instead
Email	`email.delivered`, `email.bounced`, `email.deferred`	`GET /messages`, filtered by `status` (`delivered`, `bounced` or `deferred`). Scope `messages:read`. See Message status
Email	`email.opened`, `email.clicked`, `email.complained`, `email.marked_spam`	`GET /messages/{jobId}`, whose `engagementEvents` holds `opened`, `clicked` and `complained` events. Scope `messages:read`
Email	`email.unsubscribed`, `email.dropped`, `email.rejected`	No public API equivalent
Contact	`contact.subscribed`, `contact.unsubscribed`, `contact.updated`	`GET /contacts?sortBy=updatedAt&sortOrder=desc` returns the most recently changed contacts first. Scope `contacts:read`
Campaign	`campaign.sent`, `campaign.completed`	`GET /campaigns/{id}` and read `status`: it moves from `sending` to `sent`, then `completed`. Scope `campaigns:read`

Subscribing with the API

The events array on POST /webhook-endpoints and PATCH /webhook-endpoints/{id} accepts any event type on this page, including test.event. On PATCH, the array replaces the endpoint’s whole subscription. To add one event, send the full list. The dashboard groups events as Email Events, Contact Events, Campaign Events and Push Events. It doesn’t list test.event, because test deliveries are sent whatever the subscription.

Where the payload appears in Brudcast

The delivery log stores each delivery’s data object. It appears as Request Body in the delivery details in the dashboard, and as payload on delivery records from GET /webhook-deliveries. Neither shows the envelope around it.

Verify signatures

Check X-Webhook-Signature before you trust the body.

Deliveries and retries

What counts as delivered, the backoff schedule and the delivery log.

Create an endpoint

Register device tokens

Where the tokens in push.token_invalidated come from.

Start here

Sending email

Webhooks

Recipes

Reference

Webhook events and payloads

Headers

Envelope

Delivered events

`push.token_invalidated`

`test.event`

Events that aren’t delivered

Subscribing with the API

Where the payload appears in Brudcast

Verify signatures

Deliveries and retries

Create an endpoint

Register device tokens

​Headers

​Envelope

​Delivered events

​push.token_invalidated

​test.event

​Events that aren’t delivered

​Subscribing with the API

​Where the payload appears in Brudcast

​Related

Verify signatures

Deliveries and retries

Create an endpoint

Register device tokens

Headers

Envelope

Delivered events

`push.token_invalidated`

`test.event`

Events that aren’t delivered

Subscribing with the API

Where the payload appears in Brudcast

Related