Översikt över webhookar

Sursa registrerar en händelse vid varje viktig ändring: ett kort publiceras, verifieras eller arkiveras, ett meddelande läses, en fråga förblir obesvarad. Du kan ta emot händelser på två sätt och använda båda samtidigt:

	Webhookar	Händelseflöde
Hur	Sursa skickar varje händelse till din HTTPS-adress när den inträffar.	Du läser `GET /v1/webhook-events` när du vill.
Fördröjning	Sekunder.	Så ofta som du pollar.
Kräver	En offentlig HTTPS-mottagare.	Bara en API-nyckel med rollen `admin` och omfånget `webhooks:manage`.
Passar för	Att reagera på ändringar: meddela, synka, starta ett arbetsflöde.	Batchjobb, att komma i kapp efter driftstopp, avstämning.

Båda bär samma händelser med samma id. Varje händelse sparas i flödet i 30 dagar, oavsett om någon webhook prenumererade på den eller inte.

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
}

Fält	Betydelse
`id`	Händelsens id, `evt_` och 32 hexadecimala tecken. Detsamma i varje leveransförsök och i flödet.
`type`	Vad som hände, som `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	När ändringen skedde, i UTC.
`api_version`	Versionen av API:et vars schema `data` följer.
`object`	Typ och id för objektet som händelsen gäller.
`data`	Detaljerna. Formen beror på typen och beskrivs i händelsekatalogen.
`data.previous_attributes`	I händelser av typen `*.updated`: de tidigare värdena för fälten som ändrades.
`sequence`, `payload`, `test`	Bara i webhookleveranser: positionen i webhookens ordning, nyttolastläget och om det är en testhändelse.

data innehåller bara det som vilken läsare av objektet som helst skulle kunna se via API:et. Det innehåller aldrig åtkomstlistor, andra personers behörigheter eller dolda fält. Orsaker i händelser är korta neutrala koder som no_hits, restricted eller index_failed.

Händelsetyper

Händelserna täcker följande områden:

Område	Exempel
Kort	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Verifiering	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Struktur	`collection.created`, `folder.updated`
Samarbete	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Svar	`question.unanswered`, `question.feedback_created`, `access_request.created`
Personer och åtkomst	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Källor och import	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Jobb	`job.completed`, `job.failed`, `export.ready`
Webhookar	`webhook.endpoint_disabled`, `webhook.ping`

Den fullständiga listan med schemat och ett exempel för varje händelse finns i händelsekatalogen i API-referensen. GET /v1/webhooks/catalog returnerar de typer som finns i din installation.

Nya händelsetyper läggs till med tiden, och befintliga händelser får fler fält. Händelsetyper byter aldrig namn och tas aldrig bort. Din mottagare måste hoppa över typer och fält som den inte känner till.

Vem som tar emot vad

En webhook tar bara emot en händelse om händelsens objekt är synligt för webhooken, på samma sätt som för en API-nyckel: utifrån dess roll, dataprofil och samlingar. En webhook som är begränsad till samlingen support tar aldrig emot händelser om kort i finance. Händelser om personer, nycklar, källor, importer, jobb, exporter, fakturering, appar och själva webhookarna går bara till webhookar med rollen admin.

Inom de ramarna väljer varje webhook sina händelser:

efter typ, med masker: card.* för varje korthändelse, * för varje händelse;
efter samling och efter tagg, för korthändelser.

En webhooks nyttolastläge är full (händelsen med data, standard) eller thin (händelsen utan data: din mottagare läser objektet via API:et med sin egen nyckel och ser alltid dess aktuella tillstånd).

Leveransen i korthet

En HTTPS-POST med händelsen som JSON, signerad med webhookens hemlighet i två format: Standard Webhooks (webhook-signature) och det tidigare X-KB-Signature.
Varje 2xx-svar inom 10 sekunder räknas som lyckat.
Ett misslyckande görs om i nästan tre dygn med allt längre pauser. Retry-After i ett svar 429 eller 503 respekteras; 410 inaktiverar webhooken; 10 misslyckanden i rad pausar den tills den återupptas.
Leveranserna till en webhook skickas strikt i ordning. En långsam webhook fördröjer inte andra webhookar.
Samma händelse kan komma mer än en gång: släng dubbletter utifrån webhook-id.

Ta emot webhookar går igenom en komplett mottagare, med signaturkontroller i Node.js, Python och Go.

Hantera webhookar

Uppgift	Slutpunkt
Skapa en webhook och få dess hemlighet	`POST /v1/webhooks`
Ändra mottagaradressen, händelserna eller tillståndet	`PATCH /v1/webhooks/{webhook_id}`
Skicka en testhändelse	`POST /v1/webhooks/{webhook_id}/test`
Rotera hemligheten	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Återuppta en pausad webhook	`POST /v1/webhooks/{webhook_id}/resume`
Se leveranser och svar	`GET /v1/webhooks/{webhook_id}/deliveries`
Skicka en leverans igen	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

För att hantera webhookar behövs en nyckel med rollen admin och omfånget webhooks:manage, eller en administratör i administrationsgränssnittet. En organisation kan ha högst 20 webhookar. Webhookar ingår i organisationens prisplan; utan dem svarar de här slutpunkterna 403 med koden webhooks.feature_disabled.