Un webhook est un message automatique (une requête HTTP) qu’une application envoie à une autre quand un événement se produit. Les webhooks sortants transmettent les événements de MailerPress (nouveau contact, campagne envoyée, clic…) à des services comme Zapier, Make ou votre propre application. Les webhooks entrants permettent à des services externes de créer ou mettre à jour des contacts et de démarrer des automatisations sur votre site.
Les webhooks nécessitent MailerPress Pro.
Configurer les webhooks sortants
- Allez dans MailerPress > Crochets web > Webhooks sortants.
- Dans Clé secrète, cliquez sur Générer (ou saisissez votre propre clé d’au moins 32 caractères), puis sur Copier, et collez la clé dans le service destinataire. MailerPress signe chaque requête avec cette clé et n’envoie aucun webhook sans elle.
- Laissez Envoi asynchrone activé pour envoyer les webhooks en arrière-plan avec le cron de WordPress (son planificateur de tâches). Désactivé, MailerPress les envoie pendant la requête qui déclenche l’événement, ce qui peut ralentir votre site.
- Ouvrez l’onglet des événements qui vous intéressent : Contacts, Abonnement, Campagnes ou Engagement par e-mail. L’onglet Actif liste les événements que vous avez activés.
- Pour chaque événement, activez Activé, cliquez sur Ajouter une URL sous URL des webhooks et collez l’URL de destination de votre service. Vous pouvez ajouter plusieurs URL au même événement.
- Cliquez sur Enregistrer les réglages.
- Cliquez sur Tester le webhook sur un événement pour envoyer des données d’exemple à ses URL et vérifier le résultat.
Événements disponibles
| Clé de l’événement | Nom | Données envoyées |
|---|---|---|
contact.created | Contact créé | contact_id, email, first_name, last_name, subscription_status, created_at, updated_at, tags, lists, custom_fields. Envoyé environ 5 secondes après la création du contact, pour inclure ses champs personnalisés. |
contact.updated | Contact mis à jour | Mêmes données que contact.created. |
contact.tag.addedcontact.tag.removed | Étiquette ajoutée à un contact Étiquette retirée d’un contact | contact_id, contact_email, tag_id, tag_name |
contact.list.addedcontact.list.removed | Contact ajouté à une liste Contact retiré d’une liste | contact_id, contact_email, list_id, list_name |
contact.custom_field.updated | Champ personnalisé d’un contact mis à jour | contact_id, contact_email, field_key, field_value |
contact.deleted | Contact supprimé | contact_id, email, first_name, last_name, deleted_at |
contact.unsubscribed | Contact désabonné | contact_id, email, first_name, last_name, unsubscribed_at |
subscription.confirmed | Abonnement confirmé | contact_id, email, first_name, last_name, confirmed_at |
campaign.created | Campagne créée | campaign_id, campaign_name, campaign_subject, status, campaign_type, created_at, et l’auteur (author_id, author_name, author_email) |
campaign.scheduled | Campagne planifiée | Mêmes données que campaign.created, plus scheduled_at, batch_id, scheduled_time et total_emails |
campaign.sent | Campagne envoyée | campaign_id, campaign_name, campaign_subject, total_emails, sent_emails, error_emails, sent_at et l’auteur |
email.opened | E-mail ouvert | contact_id, contact_email, campaign_id, campaign_name, campaign_subject, batch_id, opened_at |
email.clicked | Lien d’e-mail cliqué | contact_id, contact_email, campaign_id, campaign_name, campaign_subject, url, clicked_at |
email.bounced | E-mail en rebond | contact_id, email, bounced_at, bounce_type |
À savoir :
- Chaque envoi contient aussi
site_url, l’adresse de votre site. - Les événements de campagne ne concernent que les campagnes classiques. Les campagnes automatisées et les campagnes de test A/B ne les déclenchent pas.
- E-mail ouvert et Lien d’e-mail cliqué ne sont envoyés que pour des contacts connus, pas lorsque le suivi est anonyme.
- E-mail en rebond est envoyé quand la vérification de la boîte de rebonds IMAP marque un contact comme « bounced » (un e-mail à cette adresse n’a pas pu être distribué). Les rebonds signalés directement par un service d’envoi d’e-mails ne le déclenchent pas.
Format des données
MailerPress envoie une requête POST avec un corps JSON (Content-Type: application/json) qui contient la clé de l’événement, ses données et des métadonnées :
{
"event": "contact.tag.added",
"data": {
"contact_id": 42,
"contact_email": "[email protected]",
"tag_id": 3,
"tag_name": "Customers",
"site_url": "https://example.com"
},
"metadata": {
"timestamp": "2026-10-11 09:30:00",
"event_key": "contact.tag.added",
"event_name": "Contact Tag Added"
}
}La valeur de event_name suit la langue de votre site.
Vérifier la signature
Chaque requête contient un en-tête X-Webhook-Signature au format sha256=<hash>, où le hash est le HMAC-SHA256 du corps brut de la requête calculé avec votre clé secrète. Comparez-le avec votre propre calcul avant de faire confiance aux données. En PHP :
$payload = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac( 'sha256', $payload, 'VOTRE_CLE_SECRETE' );
if ( ! hash_equals( $expected, $signature ) ) {
http_response_code( 401 );
exit;
}
$event = json_decode( $payload, true );Envoi et nouvelles tentatives
- Un envoi réussit lorsque votre service répond avec un statut HTTP 2xx en moins de 30 secondes.
- En cas d’échec, MailerPress réessaie après 1 minute, puis après 5 minutes : 3 tentatives au total par URL.
- Les URL de webhook doivent être publiques. MailerPress bloque les requêtes vers des adresses locales ou de réseau privé.
- Avec Envoi asynchrone, les webhooks dépendent du cron de WordPress. S’ils arrivent en retard, consultez Comment configurer une tâche Cron WordPress à partir de votre serveur.
Configurer les webhooks entrants
- Allez dans MailerPress > Crochets web > Webhooks entrants et cliquez sur Ajouter un webhook.
- Saisissez une Description pour reconnaître le webhook dans la liste.
- Activez Activé. Un nouveau webhook est désactivé par défaut et ne traite les requêtes qu’une fois activé.
- Copiez l’URL du webhook et collez-la dans votre service externe. Elle ressemble à
https://example.com/wp-json/mailerpress/v1/webhooks/receive/webhook-1760000000000; la dernière partie est l’identifiant du webhook. - Si besoin, activez Exiger la vérification de la signature (voir plus bas).
- Dans Actions à exécuter, choisissez ce que MailerPress fait des données : Créer un contact, Mettre à jour un contact, Ajouter une étiquette et/ou Ajouter à une liste. Pour Ajouter une étiquette et Ajouter à une liste, vous pouvez choisir les étiquettes ou listes dans Sélectionner des étiquettes et Sélectionner des listes ; sinon, MailerPress utilise l’étiquette ou la liste indiquée dans la requête. Laissez les actions vides si le webhook doit seulement démarrer des automatisations.
- Cliquez sur Enregistrer les modifications.
Données acceptées par les actions
Envoyez une requête POST avec un corps JSON (les données de formulaire encodées sont aussi acceptées). Le corps ne peut pas être vide.
| Champ | Description |
|---|---|
email | Obligatoire. customer_email et user_email sont aussi acceptés. |
first_name, last_name | Prénom et nom du contact. |
subscription_status | Par exemple subscribed ou pending. Sans ce champ, Créer un contact suit votre réglage de confirmation de l’inscription : avec le double opt-in activé (les nouveaux contacts confirment par e-mail), le contact est en attente et reçoit l’e-mail de confirmation. |
tags, lists | Tableaux d’identifiants ou de noms. Un nom qui n’existe pas encore est créé. Sans liste, un nouveau contact rejoint votre liste par défaut. Pour une seule valeur, tag / tag_name et list / list_name fonctionnent aussi avec Ajouter une étiquette et Ajouter à une liste. |
custom_fields | Objet associant les clés des champs personnalisés à leurs valeurs, par exemple {"company": "Acme"}. Vous pouvez aussi envoyer un champ sous la forme "cpt:company": "Acme". Seuls les champs qui existent dans MailerPress sont enregistrés. |
Créer un contact n’ajoute que les nouvelles adresses e-mail, et Mettre à jour un contact ne modifie que les contacts existants. Sélectionnez les deux pour couvrir les deux cas.
curl -X POST "https://example.com/wp-json/mailerpress/v1/webhooks/receive/webhook-1760000000000" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","first_name":"Jane","tags":["Webinar"],"custom_fields":{"company":"Acme"}}'Exiger une signature
La vérification de signature s’adresse aux services capables de signer leurs requêtes. Quand Exiger la vérification de la signature est activé, la requête doit contenir un en-tête X-Webhook-Signature (X-Hub-Signature-256 et X-Signature sont aussi acceptés) dont la valeur est sha256= suivi du HMAC-SHA256 du corps brut, calculé avec le secret du webhook. Pour obtenir le secret, enregistrez le webhook, modifiez-le et cliquez sur Afficher le secret sous Secret du webhook. Régénérer remplace le secret, et l’ancien cesse de fonctionner.
Réponses
| Statut | Signification |
|---|---|
| 200 | Requête traitée. La réponse indique le résultat de chaque action dans handlers_executed. Si le webhook est désactivé, la réponse est aussi 200, mais avec "success": false. |
| 400 | Le corps de la requête est vide. |
| 401 | La signature est absente ou invalide. |
| 404 | Aucun webhook n’existe avec cet identifiant. |
Démarrer une automatisation depuis un webhook
Dans une automatisation, choisissez le déclencheur Crochet web reçu et saisissez l’ID du crochet web (la dernière partie de l’URL du webhook). Chaque requête reçue par ce webhook démarre l’automatisation, et les champs de la requête (email, first_name, last_name…) sont disponibles pour les étapes suivantes. Consultez Créer des workflows d’e-mails automatisés avec MailerPress Pro.
Les développeurs peuvent aussi réagir aux webhooks en PHP : voir la Référence des hooks et filtres de MailerPress.