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.

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.

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. Les modifications dans la grille des contacts, les étapes de parcours Mettre à jour un champ et les réponses enregistrées ne les déclenchent pas non plus.

lead.hot et lead.new se déclenchent quels que soient les interrupteurs et limites de vos alertes prospects : l'abonnement vaut accord.

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.