Aller au contenu

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énements
GET /webhooks vos points de terminaison
POST /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 terminaison
GET /webhooks/events

Ré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
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.

GET /webhooks → [ { id, name, url, events, hasSecret, createdAt, updatedAt } ]
GET /webhooks/{id} → le même objet
DELETE /webhooks/{id} → { "id": "cm4wh0001" }

404 quand le point de terminaison n’est pas le vôtre.

POST /webhooks/{id}/test

Envoie 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.

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.