Aller au contenu

Webhooks sortants

Un webhook pousse un événement signé vers votre système à chaque changement d’un document. Vous enregistrez une URL cible sur un doctype source, choisissez les événements, et Facet délivre chaque correspondance à votre endpoint sous forme de POST HTTP.

  • Un système externe doit réagir en quelques secondes à des documents nouveaux ou modifiés.
  • Vous alimentez un entrepôt de données ou un index de recherche depuis Facet.
  • Vous préférez votre propre code aux scripts internes à Facet.
  • Une cible HTTPS publique. Votre cible doit être une URL HTTPS sur un hôte qui se résout publiquement.
  • Le canal webhook. Votre rôle doit porter le canal de connectivité webhook ; un rôle limité au navigateur ne peut pas créer de webhooks.
  • La page. Trouvez-la sous Paramètres → Webhooks. Vous gérez les webhooks que vous avez créésà ; un administrateur voit tout.

Sélectionnez Créer un webhook puis renseignezà :

Champ Signification
Label Un nom pour la liste.
URL cible La cible HTTPS du POST.
Doctype source Le doctype à observer.
Événements Laissez vide pour tous, ou nommez ceux que vous voulez.

Facet génère un secret de signature et lie le webhook à votre compte. La liaison est définitiveà : le webhook reste le vôtre.

Chaque livraison porte l’en-tête X-Facet-Signature: sha256=<hex>. La valeur hexadécimale est le HMAC-SHA256 du corps brut exact, calculée avec votre secret comme clé. Vérifiez-la avant de faire confiance à un payload — cet exemple utilise Node.jsà :

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, secret, header) {
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Lisez le corps brut comme texte avant de l’analyser, puis vérifiez la signature sur ces octets exacts.

Le corps est une enveloppe JSON. Les champs principauxà :

Champ Signification
event Le nom de l’événement, par exemple created.
domain, doc_type, doc_id Quel document a changé.
actioner_id, cause Le compte qui a fait le changement et sa chaîne de cause.
content Le payload de l’événement. Un simple changement de document n’embarque que la trame d’identifiant {"id": "<doc_id>"}, jamais le corps du document. Appelez l’API quand vous avez besoin du contenu. Un événement opt-in qui transporte plus de données l’embarque — par exemple child_changed embarque l’enveloppe d’agrégat, et notified embarque l’enregistrement de notification.
mutation_id, emitted_at L’identité du changement et son heure.
delivery_id Unique par livraison.

Facet ajoute des en-têtes sur lesquels vous pouvez routerà : X-Facet-Event, X-Facet-Delivery et X-Facet-Mutation-Id. Voir la référence des payloads de webhook.

Ouvrez Appels sur une ligne de webhook. Chaque tentative y figure avec son statut et sa réponse. Un appel en échec réessaie à délai croissant, jusqu’à cinq tentatives. Sélectionnez Tester pour envoyer une sonde de test et lire la réponse. Vous pouvez rejouer à la main un appel du journal.

Désactivez Activé pour suspendre les livraisons. Facet conserve les réglages, le secret et le journal des appels.

Un webhook observe crm.Company pour l’événement created. Facet envoie ce corps par POST vers https://hooks.example.com/facet :

{
"webhook_id": "core.Webhook.01JCATPMKP4N82GVG2J7K4MHZZ",
"delivery_id": "01JD5R7X4K92Q8WVBN6P3A1YCD",
"event": "created",
"domain": "crm",
"doc_type": "Company",
"doc_id": "crm.Company.01JD5R6Y8K31N4TQZ9W2B5XDEF",
"mutation_id": "01JD5R6Y8K31N4TQZ9W2B5XDEG",
"actioner_id": "iam.Account.01JD5R5T2M80K3P7N1Q4S6V9WX",
"cause": {
"kind": "request",
"trace": "01JD5R6Y8K31N4TQZ9W2B5XDEG"
},
"content": {
"id": "crm.Company.01JD5R6Y8K31N4TQZ9W2B5XDEF"
},
"emitted_at": "2026-11-13T09:15:02Z"
}

Le récepteur vérifie la signature, récupère l’entreprise par son doc_id, et répond 200. Toute autre réponse compte comme un échec et lance la série de nouvelles tentativesà : 10 secondes, puis 1 minute, 5 minutes, 30 minutes et 2 heures.

Rien n’arrive.

Vérifiez, dans l’ordreà : le webhook est activéà ; le doctype source correspondà ; l’événement est dans la listeà ; le rôle lié peut toujours lire le doctype. Le journal des appels affiche un motif d’omission quand un garde-fou refuse une livraison.

La signature ne se vérifie jamais.

Vous hachez l’objet analysé. Hachez les octets du corps brut de la requête.

Une URL interne est refusée.

Les cibles doivent se résoudre publiquement. Un administrateur peut autoriser des hôtes internes nommés dans la configuration du serveur.