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

# Introduction to webhooks

> Receive real-time notifications when the state of a message or an author changes in Bodyguard.

A webhook notifies one system of a state change in another system. In practice, it is an HTTP request with a [JSON payload](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads.md#payload-structure), sent by the central system to an endpoint you control.

Bodyguard webhooks send real-time notifications when a resource changes. They are `POST` requests over HTTPS, and they follow the [Standard Webhooks](https://www.standardwebhooks.com) specification. You verify them with an open-source library instead of writing Bodyguard-specific code.

> [!WARNING]
>
> This section describes the webhooks of the new Bodyguard API. Documentation for the existing webhooks is available at [https://www.bodyguard.ai/docs/api/webhooks/introduction](https://www.bodyguard.ai/docs/api/webhooks/introduction).

## Webhooks vs. polling

Polling and webhooks are two general ways to learn about changes in another system. This comparison explains the concepts only: Bodyguard sends changes through webhooks and doesn't provide a polling API.

| | Polling | Webhooks |
| - | - | - |
| How you get events | You call an API in a loop, at a fixed interval | Bodyguard calls your endpoint when an event happens |
| Real-time notification | No | Yes |
| Quota impact | Every call counts toward your quotas | None |
| Integration effort | A scheduler and state tracking | One HTTPS endpoint |

## When to use webhooks

Webhooks let you automate actions in your application based on Bodyguard events. We recommend integrating them to keep track of the state of each resource. Typical uses:

* **Message decisions:** you receive a notification when a message is classified as `SPAM`, or when its recommended action changes.
* **Automatic author decisions:** you receive a notification when an author is banned or muted based on their behavior (for example a bot or a scammer).
* **Manual actions from the dashboard:** you receive a notification when a message is removed (its recommended action changes to `REMOVE`) or an author is banned from the Bodyguard dashboard.

## How it works

**1. Create your endpoint**

Build an endpoint on your server that accepts `POST` requests on a public HTTPS URL, and verifies the signature of each request. See [Quick start](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md) for ready-to-use examples.

**2. Register it in the dashboard**

Click the gear icon in the left menu to open **Settings**, then select **Webhooks** and click **Add webhook +**. Fill in the form: see [Configuration](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md) for each field. When you save, Bodyguard sends a [`webhook.validate`](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads#webhook-validate) event to your endpoint, which must answer with a `2xx` status code for the registration to succeed.

**3. Test the integration**

Click **Send test event** at any time to send a [`webhook.validate`](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads#webhook-validate) event and check that your endpoint receives events.

Once enabled, your webhook has the `ENABLED` [status](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md#webhook-statuses) and Bodyguard sends an HTTPS `POST` request to your endpoint each time an event you subscribed to is triggered. See [Payloads](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads.md) for the content of each request.

## Next steps

> [card] [Quick start](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md)
>
> Build an endpoint and verify each request with a Standard Webhooks library.

> [card] [Configuration](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md)
>
> Events, signing secret, contacts, and webhook statuses.

> [card] [Payloads](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads.md)
>
> Headers, payload structure, and an example for each event type.


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