Webhooks et événements
Les webhooks de compte envoient ce qui se passe dans tout votre compte vers l'URL de votre choix, en temps réel : un nouveau lead, un rendez-vous réservé, une affaire qui change d'étape. Ce sont eux qu'utilisent les intégrations Zapier et n8n, et vous pouvez aussi les diriger vers votre propre endpoint. Si vous n'utilisez que Zapier, inutile d'ajouter un webhook vous-même : la carte Zapier de la page Développeurs démarre un Zap à partir d'un modèle, et le Zap crée son propre webhook.
Ils s'ajoutent au webhook de projet de la page Réponses d'un e-mail, qui fonctionne comme avant. Un webhook de projet couvre les interactions d'un seul e-mail. Un webhook de compte couvre tous les e-mails, plus les événements ci-dessous, et il est signé de la même façon.
Ajouter un webhook
- Allez dans Développeurs dans le tableau de bord et repérez la carte Webhooks.
- Saisissez l'URL de l'endpoint (une URL
https://publique) et cochez les Événements souhaités. - Cliquez sur Ajouter un webhook et copiez le secret de signature. Il n'est affiché qu'une seule fois.
Chaque webhook indique comment il a été créé (Tableau de bord, API, Zapier ou n8n), son statut et sa dernière livraison. Envoyer un test envoie un exemple de l'événement choisi, avec "test": true dans son data. Supprimer retire le webhook. Un compte peut en avoir jusqu'à 50.
Seul le propriétaire du compte peut ajouter ou supprimer des webhooks, et il peut lui être demandé de se reconnecter d'abord.
Événements
| Événement | Se déclenche quand |
|---|---|
interaction.received | Un destinataire interagit avec un e-mail : vote, note, réponse à un quiz, clic suivi, achat, etc. Les répétitions dédoublonnées ne déclenchent rien. |
form.submitted | Un formulaire dans un e-mail est envoyé (source: "email-form"), ou un formulaire d'inscription (source: "signup-form"). |
contact.created | Un contact est ajouté à une liste. |
contact.updated | Les champs d'un contact changent. Enregistrer des données identiques ne déclenche rien. |
lead.hot | Le score d'engagement d'un contact franchit à la hausse votre seuil « prospect chaud ». |
lead.new | Un nouveau lead arrive par un formulaire d'inscription ou un formulaire dans un e-mail. |
booking.created | Un rendez-vous est réservé. |
booking.cancelled | Une réservation est annulée, avec cancelledBy. Un report ne déclenche aucun des deux événements de réservation. |
deal.created | Une affaire est créée, d'où qu'elle vienne : le tableau, une règle automatique, un parcours, une proposition ou l'API. |
deal.stage_changed | Une affaire change d'étape, gagnée et perdue comprises. |
purchase.completed | Un destinataire paie via un paiement dans l'e-mail. |
journey.completed | Un contact arrive au bout d'un parcours. Un contact qui en sort plus tôt ne compte pas. |
experiment.decided | Quelqu'un enregistre la décision d'une expérience : un gagnant, aucune différence, ou non concluant. |
experiment.completed | Les résultats finaux d'une expérience sont disponibles : l'analyse couvrant toute sa fenêtre d'observation a tourné. |
response.completed | Un destinataire a répondu à chaque bloc compté par un e-mail, par exemple à chaque question d'un sondage. Une seule fois par destinataire et par e-mail. |
review.submitted | Un destinataire a envoyé un avis depuis un bloc Demande d'avis. Se déclenche une fois par avis. |
Les événements de contact se déclenchent pour les imports, les formulaires d'inscription, l'API, les synchronisations et les connecteurs IA. Une écriture unique de plus de 500 contacts (un gros import CSV, par exemple) n'en déclenche aucun, pour qu'un import ne lance pas des milliers de workflows. Un contact ajouté dans la grille des contacts, saisi ou fusionné depuis un CSV, déclenche contact.created. Les modifications de contacts existants dans la grille ne déclenchent pas contact.updated, pas plus que les étapes de parcours Mettre à jour un champ ou les réponses enregistrées.
lead.hot et lead.new se déclenchent quels que soient les interrupteurs et limites de vos alertes prospects : l'abonnement vaut accord.
Les deux événements d'expérience portent {experiment}, la même forme que renvoie l'API des expériences. On y trouve ses variantes, le dernier result de l'analyse, la decision enregistrée avec les preuves (evidence) que l'analyse lui a fournies, et une resultsUrl. experiment.completed ne se déclenche qu'une fois par expérience, même quand la décision a été enregistrée en avance lors d'un test séquentiel. Pour une expérience dans un parcours, un gagnant désigne un chemin : decision.pathIndex.
response.completed contient l'e-mail (projectId, projectName), la clé recipient et son contact, le sendId et le variant quand un envoi l'a expédié (sinon null), les blockIds comptés et, dans answers, la réponse de chaque bloc, la même valeur que interaction.received porte dans event.value, avec firstAnsweredAt et completedAt. Un e-mail compte chaque sondage, évaluation, quiz, RSVP et formulaire que le destinataire voit, sauf si le panneau Réponses du Studio en choisit moins, et avec moins de deux il ne se déclenche jamais. Modifier une réponse ensuite ne le redéclenche pas, et une vue sans destinataire (un aperçu, un lien générique) n'est jamais complète.
review.submitted porte l'e-mail (projectId, projectName), le blockId, ce qui est noté dans subject (kind, id, title), la rating, le title et le body, le displayName choisi, verifiedPurchase, le contact et le recipient, et submittedAt.
Charge utile
Chaque livraison est un POST JSON avec la même enveloppe :
{
"id": "evt_8c1f…",
"type": "deal.stage_changed",
"createdAt": 1790000000000,
"data": {
"deal": {
"id": "deal_abc123",
"title": "Annual plan",
"value": 1200,
"currency": "USD",
"pipelineId": "owner_default",
"stageId": "proposal-sent",
"stage": "Proposal sent",
"status": "open",
"source": "manual",
"listId": "list_abc123",
"rowId": "3f6c1b0e2d…",
"email": "[email protected]"
},
"fromStageId": "meeting-booked"
}
}
id est identique pour chaque livraison d'un même événement, et il est aussi envoyé dans l'en-tête X-MailInApp-Idempotency-Key : vous pouvez ignorer sans risque une nouvelle livraison déjà traitée. createdAt est en millisecondes epoch.
Pour voir le data de chaque type d'événement, appelez GET /api/v1/events/sample ou utilisez Envoyer un test.
Vérifier la signature
Les livraisons portent les en-têtes X-MailInApp-Timestamp et X-MailInApp-Signature, calculés exactement comme pour un webhook de projet. Vérifiez-les sur le corps brut avec votre secret de signature, et rejetez les horodatages de plus de quelques minutes. La documentation du webhook de projet fournit une fonction Node.js prête à l'emploi.
Nouvelles tentatives
Votre endpoint a 5 secondes pour répondre avec un 2xx. Tout le reste (délai dépassé, statut d'erreur, redirection) est un échec, et la livraison est retentée automatiquement, à intervalles croissants, pendant plusieurs heures, avec le même corps et la même clé d'idempotence, vers l'URL actuelle du webhook. Répondez vite et faites le travail lent ensuite.
- Si votre endpoint répond
410 Gone, le webhook est désactivé. C'est ainsi que les clients REST Hooks se désabonnent. - Révoquer une clé API désactive les webhooks créés avec elle.
- Supprimer un webhook arrête ses nouvelles tentatives en attente.
S'abonner via l'API
Zapier, n8n et votre propre code peuvent gérer les webhooks avec une clé API (Authorization: Bearer mia_live_…) :
curl https://mailinapp.com/api/v1/webhooks \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'
La réponse 201 contient l'id de l'abonnement et son secret, qui signe chaque livraison. Conservez-le : il n'est plus jamais renvoyé. GET /api/v1/webhooks liste vos abonnements, et DELETE /api/v1/webhooks/{id} en supprime un. Un seul nom d'événement inconnu fait rejeter toute la requête. Ces routes acceptent 30 requêtes par minute et par clé.
Le contrat complet figure dans la spécification OpenAPI.
Lire les résultats des expériences
Avec une clé API, votre code peut lire vos expériences, par exemple pour récupérer les chiffres dès qu'arrive experiment.completed :
GET /api/v1/experimentsles liste, des plus récentes aux plus anciennes. Filtrez avecstatus,kind(sendoujourney),projectIdoujourneyId.GET /api/v1/experiments/{id}en renvoie une.GET /api/v1/experiments/{id}/resultsrenvoie l'expérience avec son rapport complet : les mêmes chiffres que l'export JSON de la page de résultats, sous forme d'agrégats uniquement.
Ces routes ne font que lire. Le verrouillage, le lancement, la décision et le déploiement d'un gagnant restent dans le tableau de bord. Elles acceptent 60 requêtes par minute et par clé. Lire les résultats d'une expérience explique ce que signifient les chiffres.