Payloads des webhooks

Bodyguard envoie chaque notification sous la forme d’une requête HTTPS POST avec un corps JSON. Les en-têtes et le payload suivent la spécification Standard Webhooks.

En-têtes

En-tête	Type	Description
`Content-Type`	string	Le format du corps. Toujours `application/json`.
`webhook-id`	string	L’identifiant unique de la notification, un UUID. Il reste identique d’une nouvelle tentative à l’autre, ce qui vous permet de détecter les doublons. Traitez-le comme une chaîne opaque et ne vous appuyez pas sur son format. Exemple : `0f8fad5b-d9cb-469f-a165-70867728950e`
`webhook-timestamp`	string	Un timestamp Unix en secondes. Il fait partie du contenu signé et vous permet de rejeter les requêtes rejouées. Exemple : `1760868930`
`webhook-signature`	string	Une ou plusieurs signatures de la requête, séparées par un espace. Chaque signature est au format `v1,<base64>`. Voir Démarrage rapide. Exemple : `v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=`

Structure du payload

Chaque payload contient les trois mêmes champs de premier niveau :

Champ	Type	Description
`type`	string	Le type d’événement, par exemple `message.updated`. Il identifie le schéma de `data`.
`timestamp`	string	Le moment où l’événement s’est produit, au format ISO 8601. Il peut différer du moment de l’envoi et de l’en-tête `webhook-timestamp`.
`data`	object	Le contenu de l’événement. Ses champs dépendent de `type`.

Les payloads ne contiennent que des identifiants et les attributs liés à l’événement. Chaque type d’événement ci-dessous indique les champs toujours présents. Utilisez reference, l’identifiant que vous avez envoyé dans votre requête d’analyse, pour rapprocher un événement de vos propres données.

Types d’événements

`message.updated`

Envoyé lorsqu’un Message est mis à jour dans un Canal. Les champs optionnels ne sont présents que si leur valeur a changé.

Champ dans `data`	Type	Toujours présent	Description
`id`	string	✅	L’identifiant Bodyguard du message.
`organizationId`	string	✅	L’identifiant de votre organisation.
`sourceId`	string	✅	L’identifiant de la Source liée au Canal.
`channelId`	string	✅	L’identifiant du Canal lié au message.
`reference`	string	✅	La référence du message.
`classifications`	string[]	Optionnel	Les nouvelles classifications du message, par exemple `["BODY_SHAMING", "INSULT"]`. Voir la taxonomie texte.
`recommendedAction`	string	Optionnel	La nouvelle action recommandée, par exemple `KEEP` ou `REMOVE`.
`type`	string	Optionnel	La nouvelle nature du contenu, par exemple `HATEFUL`.
`severity`	string	Optionnel	La nouvelle sévérité du contenu, par exemple `HIGH`.

Pour les valeurs possibles, consultez la taxonomie texte.

{
  "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`

Envoyé lorsque le statut d’un Auteur change dans une Source.

Champ dans `data`	Type	Toujours présent	Description
`id`	string	✅	L’identifiant Bodyguard de l’auteur.
`organizationId`	string	✅	L’identifiant de votre organisation.
`sourceId`	string	✅	L’identifiant de la Source liée à l’auteur.
`reference`	string	✅	La référence de l’auteur.
`status`	string	✅	Le nouveau statut de l’auteur : `ACTIVE`, `BANNED`, `MUTED` ou `SHADOW_BANNED`.
`statusExpiresAt`	string	Optionnel	La date d’expiration de l’action prise sur l’auteur, au format ISO 8601, par exemple `2026-10-26T10:15:30.706Z`. Présent uniquement lorsque l’action est temporaire, par exemple un bannissement temporaire. À l’expiration de l’action, Bodyguard envoie un nouvel événement `author.updated` avec le nouveau statut.

{
  "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`

Envoyé lorsque vous créez un webhook, lorsque vous modifiez son URL et lorsque vous cliquez sur Send test event dans le dashboard. Vous ne pouvez pas vous abonner à cet événement. Lorsque vous créez un webhook ou modifiez son URL, votre endpoint doit répondre avec un code de statut 2xx, sinon la création ou la modification échoue avec une erreur. Send test event est facultatif : utilisez-le pour vérifier que votre endpoint reçoit bien les événements. L’événement est signé comme n’importe quel autre événement, votre endpoint le vérifie donc normalement.

Champ dans `data`	Type	Description
`organizationId`	string	L’identifiant de votre organisation.

webhook.validate

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

Ignorez les champs et les types d’événements que vous ne reconnaissez pas, et répondez-y avec un code de statut 2xx. Votre endpoint continuera ainsi de fonctionner si les payloads évoluent.

Étapes suivantes

Gérer les erreurs

Découvrez ce que Bodyguard attend de votre endpoint et sa politique de nouvelle tentative.

Documentation API

Webhooks

Référence

Payloads des webhooks

En-têtes

Structure du payload

Types d’événements

`message.updated`

`author.updated`

`webhook.validate`

Étapes suivantes

Gérer les erreurs

​En-têtes

​Structure du payload

​Types d’événements

​message.updated

​author.updated

​webhook.validate

​Étapes suivantes

Gérer les erreurs

En-têtes

Structure du payload

Types d’événements

`message.updated`

`author.updated`

`webhook.validate`

Étapes suivantes