API des webhooks
Un webhook est une URL à laquelle UseNadia envoie un POST quand quelque chose se produit : une publication paraît, un commentaire ou un message arrive, une automatisation se déclenche ou recueille un e-mail. L’onglet Webhooks des Paramètres, c’est une personne qui en crée un à la main ; ces routes servent à une machine qui enregistre et retire sa propre URL, ce que fait exactement le nœud déclencheur n8n. La forme des livraisons et la façon de construire le récepteur sont décrites dans Webhooks, dans le guide. Ces routes n’existent pas dans upstream.
GET /webhooks/events le catalogue des événementsGET /webhooks vos points de terminaisonPOST /webhooks en enregistrer un (le secret est renvoyé ici, une seule fois)GET /webhooks/{id}DELETE /webhooks/{id}POST /webhooks/{id}/test une livraison d’exemple signée, pour tester le point de terminaisonLes événements
Section intitulée « Les événements »GET /webhooks/eventsRéponse 200, { "events": [ { "name", "description" } ] } :
| Événement | Quand |
|---|---|
post.published |
Une publication est parue sur un canal |
comment.received |
Un commentaire est arrivé sous une publication d’un canal connecté |
dm.received |
Un message privé est arrivé sur un canal connecté |
automation.triggered |
Un commentaire a correspondu à une automatisation et la réponse est partie |
automation.email_captured |
Une automatisation a enregistré l’adresse e-mail de la personne avec qui elle échange |
Enregistrer un point de terminaison
Section intitulée « Enregistrer un point de terminaison »POST /webhooks| Champ | Type | Obligatoire | Description |
|---|---|---|---|
name |
string |
Oui | Pour la liste des Paramètres |
url |
string |
Oui | URL HTTPS publique. Les adresses de réseau privé sont refusées |
events |
string[] |
Non | Des noms du catalogue, sans doublon. Omis : tous les événements |
integrations |
[{ id }] |
Non | Seulement ces canaux, ceux de votre organisation (un autre id : 400, rien n’est enregistré). Omis : tous les canaux |
id |
string |
Non | Votre propre id pour le point de terminaison |
{ "name": "n8n — leads", "url": "https://n8n.example.com/webhook/abc123", "events": ["automation.email_captured"], "integrations": [{ "id": "cm4ean69r0003w8w1cdomox9n" }]}Réponse 201 :
{ "id": "cm4wh0001", "name": "n8n — leads", "url": "https://n8n.example.com/webhook/abc123", "events": "automation.email_captured", "hasSecret": true, "secret": "whsec_…", "createdAt": "2026-10-20T09:30:00.000Z", "updatedAt": "2026-10-20T09:30:00.000Z"}events revient sous forme de chaîne séparée par des virgules ; null ou
vide signifie tous les événements.
Lister, lire, supprimer
Section intitulée « Lister, lire, supprimer »GET /webhooks → [ { id, name, url, events, hasSecret, createdAt, updatedAt } ]GET /webhooks/{id} → le même objetDELETE /webhooks/{id} → { "id": "cm4wh0001" }404 quand le point de terminaison n’est pas le vôtre.
Envoyer une livraison de test
Section intitulée « Envoyer une livraison de test »POST /webhooks/{id}/testEnvoie une livraison à ce seul point de terminaison, sans attendre un vrai
événement : la même enveloppe, les mêmes en-têtes et la même signature qu’une
vraie, avec "test": true ajouté à l’enveloppe et dans data un exemple
réaliste de l’événement (de faux ids test_… : rien n’a été publié). Le corps
est facultatif :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
event |
string |
Non | L’événement à simuler. Omis : le premier événement du point de terminaison, ou post.published s’il reçoit tous les événements |
L’appel attend votre point de terminaison (une tentative, pas de nouvel essai, 10 secondes de délai) et renvoie ce qu’il a répondu :
{ "delivered": true, "status": 200, "event": "post.published", "deliveryId": "0f5b2c1e-…" }status vaut null quand rien n’a répondu (délai dépassé, DNS, connexion
refusée). 404 quand le point de terminaison n’est pas le vôtre ; 400 quand
l’événement n’est pas dans le catalogue ou que le point de terminaison n’y est
pas abonné. Un récepteur qui ne doit pas agir sur un test regarde test dans
l’enveloppe : les vraies livraisons ne le portent jamais.
Vérifier une livraison
Section intitulée « Vérifier une livraison »Chaque livraison est une enveloppe JSON { id, event, occurredAt, organizationId, data }
accompagnée de quatre en-têtes :
| En-tête | Contenu |
|---|---|
X-Nadia-Event |
Le nom de l’événement |
X-Nadia-Delivery |
L’id de la livraison, pour dédoublonner |
X-Nadia-Timestamp |
Secondes Unix au moment de l’envoi |
X-Nadia-Signature |
sha256= suivi du HMAC-SHA256 en hexadécimal, avec le secret pour clé, de <timestamp>.<raw body> |
Signer l’horodatage avec le corps empêche de rejouer plus tard une livraison interceptée dont la signature serait encore valide : vérifiez la signature, puis refusez un horodatage trop éloigné de votre horloge.
const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(`${req.headers['x-nadia-timestamp']}.${rawBody}`) .digest('hex');Une livraison est retentée 3 fois, avec un délai de 10 secondes à chaque
fois, sauf sur un 4xx autre que 429 : cela veut dire que le récepteur a
rejeté le contenu lui-même, et le renvoyer n’y changerait rien. Répondez 2xx
vite et faites le travail ensuite.