> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bodyguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook payloads

> Headers, payload structure, and examples of every event Bodyguard sends to your webhook endpoint.

Bodyguard sends each notification as an HTTPS `POST` request with a JSON body. Headers and payload follow the [Standard Webhooks](https://www.standardwebhooks.com) 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](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md). 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](https://docs.bodyguard.ai/en/api-reference/concepts.md#reference) of the message. |
| `classifications` | string\[] | Optional | The new classifications of the message, for example `["BODY_SHAMING", "INSULT"]`. See the [text taxonomy](https://docs.bodyguard.ai/en/documentation/taxonomy/text-classifications.md). |
| `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](https://docs.bodyguard.ai/en/documentation/taxonomy/text-classifications.md).

```json Recommended action changed theme={null}
{
  "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"
  }
}
```

```json Classifications changed theme={null}
{
  "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](https://docs.bodyguard.ai/en/api-reference/concepts.md#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. |

```json Permanent action theme={null}
{
  "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"
  }
}
```

```json Temporary action theme={null}
{
  "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. |

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

> [!NOTE]
>
> 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

> [card] [Handling errors](https://docs.bodyguard.ai/en/api-reference/webhooks/handling-errors.md)
>
> Learn what Bodyguard expects from your endpoint, and its retry policy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.