Vue d’ensemble des webhooks

Sursa enregistre un événement pour chaque modification importante : une fiche est publiée, validée ou archivée, une annonce est lue, une question reste sans réponse. Vous pouvez recevoir les événements de deux façons, et utiliser les deux ensemble :

Les deux transportent les mêmes événements, avec les mêmes identifiants. Chaque événement est conservé dans le flux pendant 30 jours, qu’un webhook y soit abonné ou non.

L’événement

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data ne contient que ce que tout lecteur de l’objet pourrait voir par l’API. Il ne contient jamais de listes d’accès, de permissions d’autres personnes ni de champs masqués. Les motifs indiqués dans les événements sont de courts codes neutres comme no_hits, restricted ou index_failed.

Types d’événements

Les événements couvrent les domaines suivants :

La liste complète, avec le schéma et un exemple de chaque événement, figure dans le catalogue des événements de la référence de l’API. GET /v1/webhooks/catalog renvoie les types disponibles sur votre installation.

De nouveaux types d’événements s’ajoutent au fil du temps, et les événements existants gagnent des champs. Les types d’événements ne sont jamais renommés ni supprimés. Votre récepteur doit ignorer les types et les champs qu’il ne connaît pas.

Qui reçoit quoi

Un webhook ne reçoit un événement que si l’objet de l’événement lui est visible, de la même façon que pour une clé API : selon son rôle, son profil de données et ses collections. Un webhook limité à la collection support ne reçoit jamais d’événements sur les fiches de finance. Les événements qui concernent les personnes, les clés, les sources, les imports, les jobs, les exports, la facturation, les applications et les webhooks eux-mêmes ne vont qu’aux webhooks dotés du rôle admin.

Dans ce cadre, chaque webhook choisit ses événements :

• par type, avec des masques : card.* pour tous les événements des fiches, * pour tous les événements ;
• par collection et par étiquette, pour les événements des fiches.

Le mode de charge utile d’un webhook est full (l’événement avec data, par défaut) ou thin (l’événement sans data : votre récepteur lit l’objet par l’API avec sa propre clé et voit toujours son état actuel).

La livraison en bref

• Un POST HTTPS contenant l’événement en JSON, signé avec le secret du webhook dans deux formats : Standard Webhooks (webhook-signature) et l’ancien X-KB-Signature.
• Toute réponse 2xx en moins de 10 secondes est un succès.
• Un échec est relancé pendant près de trois jours, avec des pauses de plus en plus longues. Retry-After d’une réponse 429 ou 503 est respecté ; 410 désactive le webhook ; 10 échecs d’affilée le mettent en pause jusqu’à sa reprise.
• Les livraisons vers un même webhook sont envoyées strictement dans l’ordre. Un webhook lent ne retarde pas les autres webhooks.
• Le même événement peut arriver plusieurs fois : écartez les doublons grâce à webhook-id.

Recevoir des webhooks décrit pas à pas un récepteur complet, avec la vérification des signatures en Node.js, Python et Go.

Gérer les webhooks

La gestion des webhooks nécessite une clé dotée du rôle admin et de la portée webhooks:manage, ou un administrateur dans l’interface d’administration. Une organisation peut avoir jusqu’à 20 webhooks. Les webhooks font partie de l’offre de l’organisation ; sans eux, ces points de terminaison répondent 403 avec le code webhooks.feature_disabled.