Visió general dels webhooks

Sursa registra un esdeveniment per cada canvi important: es publica, es verifica o s’arxiva una entrada, es llegeix un avís, una pregunta es queda sense resposta. Podeu rebre els esdeveniments de dues maneres, i podeu fer servir totes dues alhora:

	Webhooks	Canal d’esdeveniments
Com	Sursa envia cada esdeveniment a la vostra adreça HTTPS en el moment que es produeix.	Llegiu `GET /v1/webhook-events` quan vulgueu.
Latència	Segons.	Tan sovint com consulteu el canal.
Requisits	Un receptor HTTPS públic.	Només una clau d’API amb el rol `admin` i l’àmbit `webhooks:manage`.
Adequat per a	Reaccionar als canvis: notificar, sincronitzar, iniciar un flux de treball.	Treballs per lots, posar-se al dia després d’una interrupció del servei, conciliació.

Tots dos porten els mateixos esdeveniments amb els mateixos ID. Cada esdeveniment es conserva al canal durant 30 dies, tant si hi havia algun webhook subscrit com si no.

L’esdeveniment

{
  "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
}

Camp	Significat
`id`	L’ID de l’esdeveniment, `evt_` i 32 caràcters hexadecimals. És el mateix en cada intent de lliurament i al canal.
`type`	Què ha passat, en la forma `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Quan s’ha produït el canvi, en UTC.
`api_version`	La versió de l’API de l’esquema que segueix `data`.
`object`	El tipus i l’ID de l’objecte a què fa referència l’esdeveniment.
`data`	Els detalls. La seva forma depèn del tipus i es descriu al catàleg d’esdeveniments.
`data.previous_attributes`	En els esdeveniments `*.updated`: els valors anteriors dels camps que han canviat.
`sequence`, `payload`, `test`	Només als lliuraments dels webhooks: la posició en l’ordre del webhook, el mode de càrrega útil i si és un esdeveniment de prova.

data només conté el que qualsevol lector de l’objecte podria veure a través de l’API. No conté mai llistes d’accés, els permisos d’altres persones ni camps ocults. Els motius dels esdeveniments són codis neutres breus, com ara no_hits, restricted o index_failed.

Tipus d’esdeveniment

Els esdeveniments cobreixen aquestes àrees:

Àrea	Exemples
Entrades	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Verificació	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Estructura	`collection.created`, `folder.updated`
Col·laboració	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Respostes	`question.unanswered`, `question.feedback_created`, `access_request.created`
Persones i accés	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Fonts i importació	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Treballs	`job.completed`, `job.failed`, `export.ready`
Webhooks	`webhook.endpoint_disabled`, `webhook.ping`

La llista completa, amb l’esquema i un exemple de cada esdeveniment, és al catàleg d’esdeveniments de la referència de l’API. GET /v1/webhooks/catalog retorna els tipus disponibles a la vostra instal·lació.

Amb el temps s’afegeixen tipus d’esdeveniment nous, i els esdeveniments existents guanyen camps. Els tipus d’esdeveniment no es reanomenen ni s’eliminen mai. El vostre receptor ha d’ometre els tipus i els camps que no conegui.

Qui rep què

Un webhook només rep un esdeveniment si l’objecte de l’esdeveniment és visible per al webhook, de la mateixa manera que per a una clau d’API: segons el seu rol, el seu perfil de dades i les seves col·leccions. Un webhook limitat a la col·lecció support no rep mai esdeveniments sobre entrades de finance. Els esdeveniments sobre persones, claus, fonts, importacions, treballs, exportacions, facturació, aplicacions i els mateixos webhooks només van als webhooks amb el rol admin.

Dins d’aquests límits, cada webhook tria els seus esdeveniments:

per tipus, amb màscares: card.* per a tots els esdeveniments d’entrades, * per a tots els esdeveniments;
per col·lecció i per etiqueta, per als esdeveniments d’entrades.

El mode de càrrega útil d’un webhook és full (l’esdeveniment amb data, per defecte) o thin (l’esdeveniment sense data: el vostre receptor llegeix l’objecte a través de l’API amb la seva pròpia clau i en veu sempre l’estat actual).

El lliurament, en resum

Un POST HTTPS amb l’esdeveniment en JSON, signat amb el secret del webhook en dos formats: Standard Webhooks (webhook-signature) i l’anterior X-KB-Signature.
Qualsevol resposta 2xx en menys de 10 segons és un èxit.
Un lliurament fallit es reintenta durant gairebé tres dies amb pauses cada vegada més llargues. Es respecta Retry-After en una resposta 429 o 503; 410 desactiva el webhook; 10 errors seguits el posen en pausa fins que es reprèn.
Els lliuraments a un webhook s’envien estrictament en ordre. Un webhook lent no endarrereix els altres.
El mateix esdeveniment pot arribar més d’una vegada: descarteu els duplicats per webhook-id.

Rebre webhooks explica pas a pas un receptor complet, amb la comprovació de signatures en Node.js, Python i Go.

Gestionar els webhooks

Tasca	Punt final
Crear un webhook i obtenir-ne el secret	`POST /v1/webhooks`
Canviar l’adreça, els esdeveniments o l’estat	`PATCH /v1/webhooks/{webhook_id}`
Enviar un esdeveniment de prova	`POST /v1/webhooks/{webhook_id}/test`
Fer rotar el secret	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Reprendre un webhook en pausa	`POST /v1/webhooks/{webhook_id}/resume`
Veure els lliuraments i les respostes	`GET /v1/webhooks/{webhook_id}/deliveries`
Tornar a enviar un lliurament	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Per gestionar els webhooks cal una clau amb el rol admin i l’àmbit webhooks:manage, o bé un administrador a la interfície d’administració. Una organització pot tenir fins a 20 webhooks. Els webhooks formen part del pla de l’organització; sense aquesta funció, aquests punts finals responen 403 amb el codi webhooks.feature_disabled.