Skip to main content
A webhook notifies one system of a state change in another system. In practice, it is an HTTP request with a JSON payload, 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 specification. You verify them with an open-source library instead of writing Bodyguard-specific code.
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.

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

​
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 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 for each field. When you save, Bodyguard sends a 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 event and check that your endpoint receives events.
Once enabled, your webhook has the ENABLED status and Bodyguard sends an HTTPS POST request to your endpoint each time an event you subscribed to is triggered. See Payloads for the content of each request.

​
Next steps

Quick start

Build an endpoint and verify each request with a Standard Webhooks library.

Configuration

Events, signing secret, contacts, and webhook statuses.

Payloads

Headers, payload structure, and an example for each event type.