Étapes webhook | AgentsMail.io Documentation

Une étape webhook appelle une URL à vous quand un parcours l'atteint. C'est ainsi qu'une séquence informe vos propres systèmes qu'il s'est passé quelque chose — créer une tâche, mettre à jour une fiche CRM, lancer votre propre workflow. AgentsMail ne fait jamais qu'envoyer à cette URL. Rien n'est relu dans votre réponse : seul le code de statut HTTP est conservé.

Les deux formes

Celle que vous recevez dépend du type de séquence auquel appartient l'étape, et le champ event vous l'indique sans avoir à deviner.

Séquence	`event`	Transporte
Un parcours dans lequel des personnes sont inscrites	`sequence.node.webhook`	Un contact, au moment où il passe l'étape
Une série à date fixe	`sequence.series.webhook`	Un lot de contacts — l'audience de cette étape

Une série agit sur toute une audience à la fois. Envoyer une requête par contact signifierait vingt mille requêtes à votre porte pour une liste de vingt mille contacts : l'audience est donc découpée en lots, et chaque lot est une requête. Les deux formes sont permanentes : celle par lot ne remplace pas celle à un seul contact.

Un contact

json

{
  "event": "sequence.node.webhook",
  "occurredAt": "2026-09-21T09:00:00.000Z",
  "sequence": {"id": "…", "name": "Onboarding"},
  "node": {"id": "…"},
  "contact": {
    "id": "…",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": null
  }
}

Un lot

json

{
  "event": "sequence.series.webhook",
  "occurredAt": "2026-09-21T09:00:00.000Z",
  "sequence": {"id": "…", "name": "Spring launch"},
  "node": {"id": "…"},
  "batch": {"index": 3, "size": 500},
  "contacts": [
    {
      "id": "…",
      "email": "alice@example.com",
      "firstName": "Alice",
      "lastName": null
    }
  ]
}

batch.index est le rang de ce lot dans une exécution de l'étape, compté à partir de zéro, et batch.size est le nombre de contacts qu'il transporte. Le couple est stable : si vous voyez un jour deux fois le même node.id + batch.index pour la même exécution, ce sont les mêmes contacts — c'est ce qui vous permet de reconnaître un lot déjà traité. L'audience est figée au démarrage de l'étape. Les contacts qui arrivent pendant que les lots partent appartiennent à l'étape suivante, pas à celle-ci.

Ce qui n'y figure jamais

Trois choses, et aucune par hasard :

aucun secret — pas de clé d'API, ni lien ou jeton de désabonnement, qui est une capacité et non un identifiant ;
aucun identifiant d'organisation ;
aucune réponse de votre part n'est lue — le corps que vous renvoyez est jeté sans être ouvert.

Si vous avez besoin de savoir à lequel de vos comptes appartient un appel, mettez-le dans l'URL elle-même : un chemin ou une chaîne de requête distincte par séquence fonctionne, et cela ne voyage jamais dans la charge utile.

Ce que nous exigeons de votre URL

https uniquement. Une URL en http simple est refusée à la publication.
Une adresse joignable publiquement. Les adresses privées, locales et internes sont refusées — y compris un nom d'hôte parfaitement public qui se résout vers l'une d'elles, et y compris une adresse atteinte via une redirection. Chaque saut est vérifié à nouveau.
Trois redirections au maximum.
Une réponse en moins de cinq secondes. Au-delà, l'appel est un dépassement de délai. Répondez d'abord, travaillez ensuite : accusez réception de la requête, puis faites votre traitement à part. Un lot est dimensionné pour tenir dans cette fenêtre : gardez votre gestionnaire rapide plutôt qu'exhaustif.

Tout 2xx est un succès. Tout le reste est une erreur, et rien n'est deviné à son sujet.

Quand il échoue

Un appel échoué n'est jamais retenté. Un appel webhook part au plus une fois — le retenter pourrait créer deux fois la même commande, la même tâche ou la même fiche de votre côté. Un appel qui échoue est, pour vous, un appel qui n'a jamais eu lieu.

Un échec n'arrête pas le parcours : le contact continue, et le reste de la série part. Le résultat de chaque appel est conservé, et l'écran de la séquence l'affiche sur l'étape elle-même :

Affiché	Signification
réussi	Votre endpoint a répondu un `2xx`.
erreur	Votre endpoint a répondu autre chose — le code de statut est affiché.
délai dépassé	Rien n'est revenu en cinq secondes.
destination refusée	Nos règles ont refusé l'adresse avant que quoi que ce soit ne soit envoyé.

Sur une série, l'étape indique combien de lots sont partis et combien ont échoué, avec la raison du dernier échec — par exemple 38 lots · 2 en échec (délai dépassé). Comme rien n'est retenté, cette ligne est le seul endroit où un échec partiel apparaît jamais : une étape qui semble correcte au premier coup d'œil peut quand même avoir perdu deux lots.

Ce que cela implique ailleurs

Les étapes webhook font partie du graphe de la séquence, et une étape dont l'URL enfreint nos règles fait refuser la publication de la séquence — le message nomme l'étape.