POST/v1/webhooks

Webhook maken

create_webhook

De URL moet https gebruiken, en de host ervan moet naar openbare adressen verwijzen. Privénetwerken (RFC 1918), loopback, link-local, cloudmetadata en andere netwerken voor speciale doeleinden worden geweigerd, zowel bij de registratie als bij elke verbinding. Het ondertekeningsgeheim wordt één keer getoond in de response (secret); daarna kan het alleen worden geroteerd. Een organisatie kan maximaal 20 webhooks hebben.

Het abonnement bevat eventtypes en domeinmaskers (card.*, *). Toegang wordt op dezelfde manier ingesteld als bij een API-sleutel: role, data_profile_id en collection_ids. Een event over een object dat de rol, het dataprofiel of de collecties niet kunnen zien, wordt niet geleverd. tags beperken events over kaarten tot kaarten met een van de tags. payload: thin verstuurt events zonder data. Eigen headers (headers) en uitgaande autorisatie (auth) worden versleuteld opgeslagen; responses bevatten alleen de namen van de headers en de vlaggen value_set en auth_set.

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

Idempotency-Keystring
Sleutel om een schrijfactie veilig opnieuw te proberen: 1 tot 255 afdrukbare ASCII-tekens; een UUID v4 per logische bewerking wordt aanbevolen. Een nieuwe poging met dezelfde sleutel binnen 24 uur voert de bewerking niet opnieuw uit: Sursa geeft de opgeslagen response terug (status, headers en body) met de header Idempotency-Replayed: true. Dezelfde sleutel met een andere methode, een ander pad, een andere Content-Type of een andere body geeft 409 api.idempotency_mismatch; zolang het eerste request nog loopt, 409 api.idempotency_in_progress met Retry-After: 1. Na een 5xx- of 429-response wordt de sleutel vrijgegeven en voert een nieuwe poging de bewerking opnieuw uit. De sleutel geldt per organisatie en per aanroeper (API-sleutel, gebruiker of bronsleutel).
length ≥ 1, length ≤ 255

Request-body

application/json

Object: WebhookCreate

urlstringverplicht
Ontvangstadres, alleen https://, maximaal 2048 tekens.
length ≤ 2048
descriptionstring
length ≤ 200
eventsarray of WebhookEventFilterverplicht
items ≥ 1
roleWebhookRole
data_profile_idinteger | null
collection_idsarray of integer
Collecties waarover de webhook events ontvangt. Geen waarde of een lege lijst betekent alle collecties die voor de rol en het dataprofiel beschikbaar zijn. Een sleutel die zelf tot collecties is beperkt, maakt alleen een webhook met een niet-lege lijst van zijn eigen collecties. Zonder dit veld, met een lege lijst of met een collectie buiten zijn lijst geeft het request 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string
items ≤ 50
payloadWebhookPayloadMode
headersarray of WebhookHeaderInput
items ≤ 10
authWebhookAuthInput

Responses

201Gemaakt. Dit is de enige keer dat `secret` wordt getoond.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.
Idempotency-Replayed
true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: WebhookCreated

idintegerverplicht
urlstringverplicht
descriptionstringverplicht
eventsarray of WebhookEventFilterverplicht
activebooleanverplicht
statusWebhookStatusverplicht
paused_atstring (date-time) | null
paused_reasonstring | null
failures: 10 mislukte pogingen op rij; feature_disabled: het abonnement omvat geen webhooks.
disabled_reasonstring | null
gone: de ontvanger antwoordde met 410; manual: uitgeschakeld door een beheerder.
Toegestane waarden: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRoleverplicht
data_profile_idinteger | null
Dataprofiel van de webhook (null betekent geen profiel, zoals bij een API-sleutel met dezelfde rol).
collection_idsarray of integerverplicht
Collecties waarover de webhook events ontvangt; leeg betekent alle collecties die beschikbaar zijn voor de rol en het dataprofiel.
tagsarray of stringverplicht
Events over kaarten alleen voor kaarten met een van deze tags; leeg betekent geen filter.
payloadWebhookPayloadModeverplicht
headersarray of WebhookHeaderverplicht
auth_typestring | null
Type van de uitgaande autorisatie (null betekent geen).
Toegestane waarden: bearerbasicnull
auth_setbooleanverplicht
Of er een uitgaande autorisatie is ingesteld (de waarden worden nooit teruggegeven).
previous_secret_valid_untilstring (date-time) | null
Tot wanneer leveringen ook met het vorige geheim worden ondertekend (null betekent dat er geen overlap is).
healthWebhookHealth
consecutive_failuresintegerverplicht
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)verplicht
updated_atstring (date-time)verplicht
secretstringverplicht
whsec_ gevolgd door 32 bytes in base64 (nieuwe geheimen gebruiken het standaardalfabet met opvulling, oudere base64url). Bewaar het aan de kant van de ontvanger; het verschijnt nooit meer in responses van de API. De ondertekeningssleutel volgens Standard Webhooks is de base64-decodering van het deel na whsec_.
previous_valid_untilstring (date-time) | null
Tot wanneer het vorige geheim nog wordt geaccepteerd (na een rotatie). null bij het aanmaken.

400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

409De toestand van het object staat de actie niet toe, bijvoorbeeld een duplicaat, een lopende indexering of een job die al is verwerkt.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

Retry-After
Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.
RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← webhooks · API-referentie

curl -X POST 'https://api.sursa.com/v1/webhooks' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Uitproberen

API-sleutel

De sleutel blijft in het geheugen van dit tabblad en wordt alleen naar https://api.sursa.com gestuurd.

Requests werken met de echte gegevens van je organisatie.

Idempotency-Key header

Idempotency-Key

Is dit veld leeg, dan wordt voor elk request een nieuwe sleutel gegenereerd.

Request-body (JSON)