Overzicht van webhooks

Sursa registreert een event bij elke belangrijke wijziging: een kaart wordt gepubliceerd, geverifieerd of gearchiveerd, een aankondiging wordt gelezen, een vraag blijft onbeantwoord. Je kunt events op twee manieren ontvangen en beide samen gebruiken:

Beide bevatten dezelfde events met dezelfde ID’s. Elk event blijft 30 dagen in de feed, of er nu een webhook op geabonneerd was of niet.

Het event

{
  "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 bevat alleen wat elke lezer van het object via de API zou kunnen zien. Het bevat nooit toegangslijsten, de rechten van andere mensen of verborgen velden. Redenen in events zijn korte neutrale codes zoals no_hits, restricted of index_failed.

Eventtypes

Events bestrijken deze gebieden:

De volledige lijst met het schema en een voorbeeld van elk event staat in de eventcatalogus van de API-referentie. GET /v1/webhooks/catalog geeft de types terug die op je installatie beschikbaar zijn.

Na verloop van tijd komen er nieuwe eventtypes bij, en bestaande events krijgen er velden bij. Eventtypes krijgen nooit een andere naam en worden nooit verwijderd. Je ontvanger moet types en velden die hij niet kent, overslaan.

Wie wat ontvangt

Een webhook ontvangt een event alleen als het object van het event zichtbaar is voor de webhook, op dezelfde manier als voor een API-sleutel: op basis van zijn rol, zijn dataprofiel en zijn collecties. Een webhook die beperkt is tot de collectie support, ontvangt nooit events over kaarten in finance. Events over mensen, sleutels, bronnen, imports, jobs, exports, facturering, apps en de webhooks zelf gaan alleen naar webhooks met de rol admin.

Binnen die grenzen kiest elke webhook zijn events:

• op type, met maskers: card.* voor elk event over kaarten, * voor elk event;
• op collectie en op tag, voor events over kaarten.

De payloadmodus van een webhook is full (het event met data, de standaard) of thin (het event zonder data: je ontvanger leest het object via de API met een eigen sleutel en ziet altijd de huidige toestand).

De levering in het kort

• Een HTTPS-POST met het event als JSON, ondertekend met het geheim van de webhook in twee formaten: Standard Webhooks (webhook-signature) en het eerdere X-KB-Signature.
• Elk 2xx-antwoord binnen 10 seconden geldt als geslaagd.
• Een mislukte levering wordt bijna drie dagen lang opnieuw geprobeerd, met steeds langere pauzes. Retry-After in een antwoord 429 of 503 wordt gerespecteerd; 410 schakelt de webhook uit; 10 mislukkingen op rij pauzeren hem tot hij weer wordt hervat.
• Leveringen aan één webhook worden strikt op volgorde verstuurd. Een trage webhook houdt andere webhooks niet op.
• Hetzelfde event kan meer dan eens aankomen: filter duplicaten op webhook-id.

Webhooks ontvangen loopt een volledige ontvanger door, met controle van de handtekening in Node.js, Python en Go.

Webhooks beheren

Voor het beheren van webhooks is een sleutel met de rol admin en de scope webhooks:manage nodig, of een beheerder in de beheeromgeving. Een organisatie kan maximaal 20 webhooks hebben. Webhooks maken deel uit van het abonnement van de organisatie; zonder webhooks antwoorden deze endpoints met 403 en de code webhooks.feature_disabled.