POST/v1/webhooks

Opret en webhook

create_webhook

URL’en skal bruge https, og dens værtsnavn skal pege på offentlige adresser. Private netværk (RFC 1918), loopback, link-local, cloudmetadata og andre netværk til særlige formål afvises både ved registreringen og ved hver forbindelse. Signeringshemmeligheden vises én gang i svaret (secret); derefter kan den kun roteres. En organisation kan højst have 20 webhooks.

Abonnementet angiver hændelsestyper og domænemasker (card.*, *). Adgang angives på samme måde som for en API-nøgle: role, data_profile_id og collection_ids. En hændelse om et objekt, som rollen, dataprofilen eller samlingerne ikke kan se, leveres ikke. tags begrænser hændelser for kort til kort med et hvilket som helst af taggene. payload: thin sender hændelser uden data. Brugerdefinerede headere (headers) og udgående autorisation (auth) gemmes krypteret; svarene indeholder kun headernes navne og flagene value_set og auth_set.

Autentificering

Send en API-nøgle i headeren Authorization: Authorization: Bearer <nøgle>.

Headerparametre

Idempotency-Keystring
Nøgle til et sikkert nyt forsøg på en skrivning: 1 til 255 printbare ASCII-tegn; en UUID v4 pr. logisk operation anbefales. Et nyt forsøg med samme nøgle inden for 24 timer udfører ikke operationen igen: det returnerer det gemte svar (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøgle med en anden metode, sti, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første anmodning stadig kører, 409 api.idempotency_in_progress med Retry-After: 1. Efter et 5xx- eller 429-svar frigives nøglen, og et nyt forsøg udfører operationen igen. Nøglen gælder for organisationen og den kaldende part (API-nøgle, bruger eller nøgle til en brugerdefineret kilde).
length ≥ 1, length ≤ 255

Anmodningens brødtekst

application/json

Objekt: WebhookCreate

urlstringpåkrævet
Modtagerens URL, kun https://, op til 2048 tegn.
length ≤ 2048
descriptionstring
length ≤ 200
eventsarray of WebhookEventFilterpåkrævet
items ≥ 1
roleWebhookRole
data_profile_idinteger | null
collection_idsarray of integer
Samlinger, som webhooken modtager hændelser om. Ingen værdi eller en tom liste betyder alle samlinger, der er tilgængelige for rollen og dataprofilen. En nøgle, der selv er begrænset til samlinger, opretter kun en webhook med en ikke-tom liste over sine egne samlinger. Uden dette felt, med en tom liste eller med en samling uden for dens liste returnerer anmodningen 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string
items ≤ 50
payloadWebhookPayloadMode
headersarray of WebhookHeaderInput
items ≤ 10
authWebhookAuthInput

Svar

201Oprettet. Det er den eneste gang, `secret` vises.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.
Idempotency-Replayed
true betyder, at svaret blev afspillet igen fra det gemte svar for denne Idempotency-Key: operationen blev ikke udført igen.

application/json

Objekt: WebhookCreated

idintegerpåkrævet
urlstringpåkrævet
descriptionstringpåkrævet
eventsarray of WebhookEventFilterpåkrævet
activebooleanpåkrævet
statusWebhookStatuspåkrævet
paused_atstring (date-time) | null
paused_reasonstring | null
failures: 10 mislykkede forsøg i træk; feature_disabled: prisplanen omfatter ikke webhooks.
disabled_reasonstring | null
gone: modtageren svarede 410; manual: deaktiveret af en administrator.
Tilladte værdier: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRolepåkrævet
data_profile_idinteger | null
Webhookens dataprofil (null betyder ingen profil, som for en API-nøgle med samme rolle).
collection_idsarray of integerpåkrævet
Samlinger, som webhooken modtager hændelser om; tom betyder alle samlinger, som rollen og dataprofilen har adgang til.
tagsarray of stringpåkrævet
Hændelser for kort kun for kort med et af disse tags; tom betyder intet filter.
payloadWebhookPayloadModepåkrævet
headersarray of WebhookHeaderpåkrævet
auth_typestring | null
Typen af udgående autorisation (null betyder ingen).
Tilladte værdier: bearerbasicnull
auth_setbooleanpåkrævet
Om udgående autorisation er angivet (værdierne returneres aldrig).
previous_secret_valid_untilstring (date-time) | null
Indtil hvornår leveringer også signeres med den tidligere hemmelighed (null betyder, at der ikke er noget overlap).
healthWebhookHealth
consecutive_failuresintegerpåkrævet
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)påkrævet
updated_atstring (date-time)påkrævet
secretstringpåkrævet
whsec_ efterfulgt af 32 byte i base64 (nye hemmeligheder bruger standardalfabetet med udfyldning, ældre bruger base64url). Gem den hos modtageren; den vises aldrig igen i API’ets svar. Signeringsnøglen efter Standard Webhooks er base64-afkodningen af delen efter whsec_.
previous_valid_untilstring (date-time) | null
Indtil hvornår den tidligere hemmelighed stadig accepteres (efter en rotation). null ved oprettelsen.

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

409Objektets tilstand tillader ikke handlingen, fx en dublet, en igangværende indeksering eller et job, der allerede er behandlet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

Retry-After
Antal sekunder, du skal vente, før du prøver anmodningen igen.
RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← webhooks · API-reference

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"

Afprøv

API-nøgle

Nøglen gemmes kun i denne fanes hukommelse og sendes kun til https://api.sursa.com.

Anmodningerne udføres på din organisations rigtige data.

Idempotency-Key header

Idempotency-Key

Er feltet tomt, genereres en ny nøgle for hver anmodning.

Anmodningens brødtekst (JSON)