Oversikt over webhooks

Sursa registrerer en hendelse for hver viktig endring: Et kort publiseres, verifiseres eller arkiveres, en kunngjøring blir lest, et spørsmål blir stående ubesvart. Du kan motta hendelser på to måter og bruke begge samtidig:

Begge har de samme hendelsene med de samme ID-ene. Hver hendelse lagres i feeden i 30 dager, uansett om noen webhook abonnerte på den eller ikke.

Hendelsen

{
  "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 inneholder bare det enhver leser av objektet kunne se gjennom API-et. Det inneholder aldri tilgangslister, andres tillatelser eller skjulte felt. Årsaker i hendelser er korte nøytrale koder som no_hits, restricted eller index_failed.

Hendelsestyper

Hendelsene dekker disse områdene:

Den fullstendige listen med skjemaet og et eksempel på hver hendelse finnes i hendelseskatalogen i API-referansen. GET /v1/webhooks/catalog returnerer typene som er tilgjengelige i installasjonen din.

Nye hendelsestyper legges til over tid, og eksisterende hendelser får nye felt. Hendelsestyper får aldri nytt navn og fjernes aldri. Mottakeren din må hoppe over typer og felt den ikke kjenner.

Hvem som mottar hva

Et endepunkt mottar en hendelse bare hvis objektet i hendelsen er synlig for endepunktet, på samme måte som for en API-nøkkel: etter rollen, dataprofilen og samlingene. Et endepunkt som er begrenset til samlingen support, mottar aldri hendelser om kort i finance. Hendelser om personer, nøkler, kilder, importer, jobber, eksporter, fakturering, applikasjoner og selve webhookene går bare til endepunkter med rollen admin.

Innenfor dette velger hvert endepunkt sine hendelser:

• etter type, med masker: card.* for alle korthendelser, * for alle hendelser;
• etter samling og etter tagg, for korthendelser.

Nyttelastmodusen for et endepunkt er full (hendelsen med data, standard) eller thin (hendelsen uten data: Mottakeren din leser objektet gjennom API-et med sin egen nøkkel og ser alltid den nåværende tilstanden).

Levering i korte trekk

• En HTTPS-POST med hendelsen som JSON, signert med endepunktets hemmelighet i to formater: Standard Webhooks (webhook-signature) og det tidligere X-KB-Signature.
• Ethvert 2xx-svar innen 10 sekunder regnes som vellykket.
• En mislykket leveranse prøves på nytt i nesten tre døgn med stadig lengre pauser. Retry-After i et 429- eller 503-svar respekteres, 410 deaktiverer endepunktet, og 10 feil på rad setter det på pause til det blir gjenopptatt.
• Leveranser til samme endepunkt sendes strengt i rekkefølge. Et tregt endepunkt forsinker ikke andre endepunkter.
• Den samme hendelsen kan komme mer enn én gang: Forkast duplikater etter webhook-id.

Veiledningen Motta webhooks går gjennom en komplett mottaker, med validering av signaturen i Node.js, Python og Go.

Administrere endepunkter

For å administrere endepunkter trenger du en nøkkel med rollen admin og scopet webhooks:manage eller en administrator i administrasjonsgrensesnittet. En organisasjon kan ha opptil 20 endepunkter. Webhooks er en del av organisasjonens prisplan; uten dem svarer disse operasjonene 403 med koden webhooks.feature_disabled.