Webhook payloads

Bodyguard sends each notification as an HTTPS POST request with a JSON body. Headers and payload follow the Standard Webhooks specification.

Headers

Header	Type	Description
`Content-Type`	string	The format of the body. Always `application/json`.
`webhook-id`	string	The unique identifier of the notification, a UUID. It stays the same across retries, so you can use it to detect duplicates. Treat it as an opaque string and do not rely on its format. Example: `0f8fad5b-d9cb-469f-a165-70867728950e`
`webhook-timestamp`	string	A Unix timestamp in seconds. It is part of the signed content and lets you reject replayed requests. Example: `1760868930`
`webhook-signature`	string	One or more signatures of the request, separated by a space. Each signature is formatted as `v1,<base64>`. See Quick start. Example: `v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=`

Payload structure

Every payload has the same three top-level fields:

Field	Type	Description
`type`	string	The event type, for example `message.updated`. It identifies the schema of `data`.
`timestamp`	string	When the event occurred, as an ISO 8601 date. It can differ from the time of delivery, and from the `webhook-timestamp` header.
`data`	object	The content of the event. Its fields depend on `type`.

Payloads only carry identifiers and the attributes related to the event. Each event type below shows which fields are always present. Use reference, the identifier you sent in your analyze request, to match an event with your own records.

Event types

`message.updated`

Sent when a Message is updated within a Channel. Optional fields are only present when their value changed.

Field in `data`	Type	Always present	Description
`id`	string	✅	The Bodyguard identifier of the message.
`organizationId`	string	✅	The identifier of your organization.
`sourceId`	string	✅	The identifier of the Source bound to the Channel.
`channelId`	string	✅	The identifier of the Channel bound to the message.
`reference`	string	✅	The reference of the message.
`classifications`	string[]	Optional	The new classifications of the message, for example `["BODY_SHAMING", "INSULT"]`. See the text taxonomy.
`recommendedAction`	string	Optional	The new recommended action, for example `KEEP` or `REMOVE`.
`type`	string	Optional	The new nature of the content, for example `HATEFUL`.
`severity`	string	Optional	The new severity of the content, for example `HIGH`.

For the possible values, see the text taxonomy.

{
  "type": "message.updated",
  "timestamp": "2026-10-19T10:15:30.706Z",
  "data": {
    "id": "d6a1f3b2-7c1e-4b8e-9a54-0e2f6c1b7a90",
    "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe",
    "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f",
    "channelId": "cbc601f1-dec6-4594-9476-51628a17499a",
    "reference": "comment-48213",
    "recommendedAction": "REMOVE"
  }
}

{
  "type": "message.updated",
  "timestamp": "2026-10-19T10:15:30.706Z",
  "data": {
    "id": "d6a1f3b2-7c1e-4b8e-9a54-0e2f6c1b7a90",
    "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe",
    "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f",
    "channelId": "cbc601f1-dec6-4594-9476-51628a17499a",
    "reference": "comment-48213",
    "classifications": ["BODY_SHAMING", "INSULT"],
    "type": "HATEFUL",
    "severity": "HIGH",
    "recommendedAction": "REMOVE"
  }
}

`author.updated`

Sent when the status of an Author changes within a Source.

Field in `data`	Type	Always present	Description
`id`	string	✅	The Bodyguard identifier of the author.
`organizationId`	string	✅	The identifier of your organization.
`sourceId`	string	✅	The identifier of the Source bound to the author.
`reference`	string	✅	The reference of the author.
`status`	string	✅	The new status of the author: `ACTIVE`, `BANNED`, `MUTED`, or `SHADOW_BANNED`.
`statusExpiresAt`	string	Optional	The date when the action on the author expires, as an ISO 8601 date, for example `2026-10-26T10:15:30.706Z`. Only present when the action is temporary, for example a temporary ban. When the action expires, Bodyguard sends another `author.updated` event with the new status.

{
  "type": "author.updated",
  "timestamp": "2026-10-19T10:15:30.706Z",
  "data": {
    "id": "7b3e9c10-5f2a-4d6b-8c41-a9d0e3f21b58",
    "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe",
    "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f",
    "reference": "user-1a2b3c4d",
    "status": "BANNED"
  }
}

{
  "type": "author.updated",
  "timestamp": "2026-10-19T10:15:30.706Z",
  "data": {
    "id": "7b3e9c10-5f2a-4d6b-8c41-a9d0e3f21b58",
    "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe",
    "sourceId": "81310ae5-228e-438e-9720-35f737b9ca9f",
    "reference": "user-1a2b3c4d",
    "status": "MUTED",
    "statusExpiresAt": "2026-10-26T10:15:30.706Z"
  }
}

`webhook.validate`

Sent when you create a webhook, when you change its URL, and when you click Send test event in the dashboard. You cannot subscribe to this event. When you create a webhook or change its URL, your endpoint must answer with a 2xx status code, otherwise the creation or update fails with an error. Send test event is optional: use it to check that your endpoint receives events. The event is signed like any other event, so your endpoint verifies it as usual.

Field in `data`	Type	Description
`organizationId`	string	The identifier of your organization.

webhook.validate

{
  "type": "webhook.validate",
  "timestamp": "2026-10-19T10:15:30.706Z",
  "data": {
    "organizationId": "5d849494-2b0e-49fc-85d5-7197ca62d7fe"
  }
}

Ignore fields and event types you do not recognize, and answer them with a 2xx status code. This keeps your endpoint working if the payloads evolve.

Next steps

Handling errors

Learn what Bodyguard expects from your endpoint, and its retry policy.

API Documentation

Webhooks

Reference

Headers

Payload structure

Event types

`message.updated`

`author.updated`

`webhook.validate`

Next steps

Handling errors

​Headers

​Payload structure

​Event types

​message.updated

​author.updated

​webhook.validate

​Next steps

Handling errors

Headers

Payload structure

Event types

`message.updated`

`author.updated`

`webhook.validate`

Next steps