Contenu des webhooks

Les webhooks sont des requêtes HTTP POST contenant du JSON. Créez un webhook avec l’API Webhooks et consultez les événements disponibles avec la liste des déclencheurs. Les événements disponibles dépendent des modules installés.

Enveloppe

Chaque clé est un identifiant d’événement. Sa valeur est un tableau de charges utiles. Parcourez toutes les clés et toutes les entrées, même si une requête ne contient qu’un événement. Chaque entrée inclut timestamp, au format ISO 8601. Cet horodatage correspond à la mise en file ou au traitement du webhook, selon le mode de transport ; il ne remplace pas la date métier de l’entité.

Exemple abrégé : contact contient normalement davantage de propriétés.

{
  "mautic.lead_points_change": [
    {
      "contact": {"id": 123},
      "points": {"old_points": 5, "new_points": 10},
      "timestamp": "2026-10-01T12:00:00+00:00"
    }
  ]
}

Événements

Les clés ci-dessous s’ajoutent à timestamp. Les objets imbriqués sont sérialisés dans le contexte de l’événement : leur contenu n’est pas garanti identique à celui des réponses REST. Acceptez les propriétés supplémentaires et les valeurs nulles.

Événement	Clés de la charge utile	Remarques
mautic.lead_post_save_new	contact	Contact nouvellement identifié.
mautic.lead_post_save_update	contact	Contact modifié.
mautic.lead_post_delete	id, contact	Utilisez id séparément ; l’entité supprimée peut avoir un identifiant nul.
mautic.lead_points_change	contact, points	points.old_points et points.new_points sont des entiers.
mautic.lead_channel_subscription_changed	contact, channel, old_status, new_status	Statuts textuels : contactable, unsubscribed, bounced, manual.
mautic.lead_company_change	added, contact, company	added est un booléen : association ajoutée ou retirée.
mautic.company_post_save	company	Société créée ou modifiée.
mautic.company_post_delete	id, company	Utilisez id séparément pour identifier la société supprimée.
mautic.lead_list_change	contact, segment, action	action vaut added ou removed.
mautic.email_on_send	email, contact, contentHash, idHash, subject, source, headers	Avec includeDetails, également content et tokens. Cet événement d’envoi ne prouve pas la réception.
mautic.email_on_open	stat	Statistique d’ouverture, avec les données du contact et de l’e-mail associés.
mautic.form_on_submit	submission	Soumission de formulaire et données associées.
mautic.page_on_hit	hit	Enregistrement de visite et données associées.
mautic.sms_on_send	smsId, contact, content	Peut également inclure transport_message_id si le transport le fournit.

En-têtes et signature

Content-Type vaut application/json. X-Origin-Base-URL contient l’URL de l’instance émettrice ; cet en-tête seul ne prouve pas son identité.

Lorsqu’un secret est configuré, Webhook-Signature contient le HMAC-SHA256 binaire du corps HTTP exact, encodé en Base64 :

Base64(HMAC-SHA256(secret, rawRequestBody))

Vérifiez la signature avec une comparaison en temps constant, avant de traiter le contenu. Ne décodez puis ne réencodez pas le JSON avant le calcul : cela peut modifier les octets signés. Sans secret configuré, aucune signature utilisable n’est fournie.

Livraison et confidentialité

Répondez rapidement avec un statut 2xx après avoir accepté la requête. Le client HTTP ne suit pas les redirections. Prévoyez un traitement idempotent : les reprises de transport peuvent entraîner des doublons ; l’ordre d’arrivée n’est pas un ordre métier garanti.

Les données peuvent contenir des informations personnelles. includeDetails ajoute notamment le contenu et les tokens de l’e-mail envoyé. Activez cette option uniquement si votre destinataire en a besoin.