Oversigt over webhooks

Sursa registrerer en hændelse for hver vigtig ændring: Et kort publiceres, verificeres eller arkiveres, en meddelelse læses, et spørgsmål forbliver ubesvaret. Du kan modtage hændelser på to måder og bruge begge samtidig:

	Webhooks	Hændelsesfeed
Hvordan	Sursa sender hver hændelse til din HTTPS-adresse, når den sker.	Du læser `GET /v1/webhook-events`, når du vil.
Forsinkelse	Sekunder.	Så ofte, som du poller.
Kræver	En offentlig HTTPS-modtager.	Kun en API-nøgle med rollen `admin` og scopet `webhooks:manage`.
God til	At reagere på ændringer: give besked, synkronisere, starte et workflow.	Batchjob, indhentning efter nedetid, afstemning.

Begge leverer de samme hændelser med de samme id’er. Hver hændelse gemmes i feedet i 30 dage, uanset om en webhook abonnerede på den eller ej.

Hændelsen

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

Felt	Betydning
`id`	Hændelsens id, `evt_` og 32 hexadecimale tegn. Det samme i hvert leveringsforsøg og i feedet.
`type`	Hvad der skete, som `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Hvornår ændringen skete, i UTC.
`api_version`	Den API-version, hvis skema `data` følger.
`object`	Typen og id’et for det objekt, hændelsen handler om.
`data`	Detaljerne. Formen afhænger af typen og er beskrevet i hændelseskataloget.
`data.previous_attributes`	I `*.updated`-hændelser: de tidligere værdier af de felter, der er ændret.
`sequence`, `payload`, `test`	Kun i webhook-leveringer: positionen i slutpunktets rækkefølge, payload-tilstanden, og om det er en testhændelse.

data indeholder kun det, som enhver læser af objektet kunne se via API’et. Det indeholder aldrig adgangslister, andre personers tilladelser eller skjulte felter. Årsager i hændelser er korte neutrale koder som no_hits, restricted eller index_failed.

Hændelsestyper

Hændelserne dækker disse områder:

Område	Eksempler
Kort	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Verificering	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktur	`collection.created`, `folder.updated`
Samarbejde	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Svar	`question.unanswered`, `question.feedback_created`, `access_request.created`
Personer og adgang	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Kilder og import	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Job	`job.completed`, `job.failed`, `export.ready`
Webhooks	`webhook.endpoint_disabled`, `webhook.ping`

Den komplette liste med skemaet og et eksempel for hver hændelse står i hændelseskataloget i API-referencen. GET /v1/webhooks/catalog returnerer de typer, der er tilgængelige i din installation.

Nye hændelsestyper tilføjes løbende, og eksisterende hændelser får nye felter. Hændelsestyper bliver aldrig omdøbt eller fjernet. Din modtager skal springe typer og felter over, som den ikke kender.

Hvem modtager hvad

Et slutpunkt modtager kun en hændelse, hvis hændelsens objekt er synligt for slutpunktet, på samme måde som for en API-nøgle: efter dets rolle, dataprofil og samlinger. Et slutpunkt, der er begrænset til samlingen support, modtager aldrig hændelser om kort i finance. Hændelser om personer, nøgler, kilder, importer, job, eksporter, fakturering, apps og selve webhooks går kun til slutpunkter med rollen admin.

Inden for disse rammer vælger hvert slutpunkt sine hændelser:

efter type med masker: card.* for alle korthændelser, * for alle hændelser;
efter samling og tag for korthændelser.

Et slutpunkts payload-tilstand er full (hændelsen med data, standard) eller thin (hændelsen uden data: Din modtager læser objektet via API’et med sin egen nøgle og ser altid dets aktuelle tilstand).

Levering kort fortalt

En HTTPS-POST med hændelsen som JSON, signeret med slutpunktets hemmelighed i to formater: Standard Webhooks (webhook-signature) og det tidligere X-KB-Signature.
Ethvert 2xx-svar inden for 10 sekunder er en succes.
En mislykket levering forsøges igen i næsten tre døgn med stadig længere pauser. Retry-After i et 429- eller 503-svar respekteres; 410 deaktiverer slutpunktet; 10 mislykkede leveringer i træk sætter det på pause, indtil det genoptages.
Leveringer til ét slutpunkt sendes strengt i rækkefølge. Et langsomt slutpunkt forsinker ikke andre slutpunkter.
Den samme hændelse kan komme mere end én gang: Kassér dubletter efter webhook-id.

Modtag webhooks gennemgår en komplet modtager med validering af signaturer i Node.js, Python og Go.

Administrér slutpunkter

Opgave	Operation
Opret et slutpunkt, og få dets hemmelighed	`POST /v1/webhooks`
Ændr adressen, hændelserne eller tilstanden	`PATCH /v1/webhooks/{webhook_id}`
Send en testhændelse	`POST /v1/webhooks/{webhook_id}/test`
Rotér hemmeligheden	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Genoptag et slutpunkt, der er sat på pause	`POST /v1/webhooks/{webhook_id}/resume`
Se leveringer og svar	`GET /v1/webhooks/{webhook_id}/deliveries`
Send en levering igen	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Administration af slutpunkter kræver en nøgle med rollen admin og scopet webhooks:manage eller en administrator i administrationsgrænsefladen. En organisation kan have op til 20 slutpunkter. Webhooks er en del af organisationens prisplan; uden dem svarer disse operationer 403 med koden webhooks.feature_disabled.