Mine sisu juurde
Sursa Developers

POST/v1/webhooks

Veebihaagi loomine

create_webhook

URL peab kasutama protokolli https ja selle host peab lahenduma avalikeks aadressideks. Privaatsed (RFC 1918), tagasisilmus-, link-local-, pilve metaandmete ja muud eriotstarbelised võrgud lükatakse tagasi nii registreerimisel kui ka igal ühendusel. Allkirjastamise saladust näidatakse vastuses üks kord (secret); pärast seda saab seda ainult uuendada. Organisatsioonil võib olla kuni 20 veebihaaki.

Tellimus loetleb sündmusetüübid ja sündmuste rühma maskid (card.*, *). Juurdepääs määratakse samamoodi nagu API-võtmel: role, data_profile_id ja collection_ids. Sündmust objekti kohta, mida roll, andmeprofiil või kogud ei näe, ei edastata. tags piirab kaardisündmused kaartidega, millel on mõni neist siltidest. payload: thin saadab sündmused ilma väljata data. Kohandatud päised (headers) ja väljuv autoriseerimine (auth) salvestatakse krüpteeritult; vastused sisaldavad ainult päiste nimesid ning lippe value_set ja auth_set.

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Päiseparameetrid

  • Idempotency-Keystring

    Võti kirjutamistoimingu turvaliseks kordamiseks: 1–255 prinditavat ASCII-märki; soovitatav on UUID v4 iga loogilise toimingu kohta. Kordus sama võtmega 24 tunni jooksul ei käivita toimingut uuesti: tagastatakse salvestatud vastus (olek, päised ja keha) päisega Idempotency-Replayed: true. Sama võti teise meetodi, tee, Content-Type või kehaga tagastab 409 api.idempotency_mismatch; kuni esimene päring veel töötab, tagastatakse 409 api.idempotency_in_progress koos päisega Retry-After: 1. Pärast vastust 5xx või 429 võti vabastatakse ja kordus käivitab toimingu uuesti. Võti kehtib organisatsiooni ja päringu tegija piires (API-võti, kasutaja või kohandatud allika võti).

    length ≥ 1, length ≤ 255

Päringu keha

application/json

Objekt: WebhookCreate

  • urlstringkohustuslik

    Vastuvõtja URL, ainult https://, kuni 2048 märki.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterkohustuslik

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    Kogud, mille kohta veebihaak sündmusi saab. Puuduv väärtus või tühi loend tähendab kõiki rollile ja andmeprofiilile kättesaadavaid kogusid. Võti, mis on ise kogudega piiratud, loob veebihaagi ainult oma kogude mittetühja loendiga. Ilma selle väljata, tühja loendiga või selle loendist väljaspool oleva koguga tagastab päring 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

Vastused

201Loodud. See on ainus kord, kui `secret` näidatakse.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

  • Idempotency-Replayed

    true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: WebhookCreated

  • idintegerkohustuslik
  • urlstringkohustuslik
  • descriptionstringkohustuslik
  • eventsarray of WebhookEventFilterkohustuslik
  • activebooleankohustuslik
  • statusWebhookStatuskohustuslik
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: 10 järjestikust ebaõnnestunud katset; feature_disabled: pakett ei sisalda veebihaake.

  • disabled_reasonstring | null

    gone: vastuvõtja vastas koodiga 410; manual: administraator keelas.

    Lubatud väärtused: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRolekohustuslik
  • data_profile_idinteger | null

    Veebihaagi andmeprofiil (null tähendab profiili puudumist, nagu sama rolliga API-võtmel).

  • collection_idsarray of integerkohustuslik

    Kogud, mille sündmusi veebihaak saab; tühi tähendab kõiki rollile ja andmeprofiilile kättesaadavaid kogusid.

  • tagsarray of stringkohustuslik

    Kaardisündmused ainult kaartide kohta, millel on mõni neist siltidest; tühi tähendab, et filtrit pole.

  • payloadWebhookPayloadModekohustuslik
  • headersarray of WebhookHeaderkohustuslik
  • auth_typestring | null

    Väljamineva autoriseerimise tüüp (null tähendab, et seda pole).

    Lubatud väärtused: bearerbasicnull

  • auth_setbooleankohustuslik

    Kas väljaminev autoriseerimine on määratud (väärtusi ei tagastata mitte kunagi).

  • previous_secret_valid_untilstring (date-time) | null

    Mis ajani allkirjastatakse edastused ka eelmise saladusega (null tähendab, et kattuvusaega pole).

  • healthWebhookHealth
  • consecutive_failuresintegerkohustuslik
  • 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)kohustuslik
  • updated_atstring (date-time)kohustuslik
  • secretstringkohustuslik

    whsec_, millele järgneb 32 baiti base64-kodeeringus (uued saladused kasutavad standardset tähestikku koos täitemärkidega, vanemad base64url-kodeeringut). Salvestage see vastuvõtja poolel; API vastustes seda enam kunagi ei esine. Standard Webhooks allkirjastamise võti on whsec_ järel oleva osa base64-dekodeering.

  • previous_valid_untilstring (date-time) | null

    Mis ajani eelmist saladust veel aktsepteeritakse (pärast uuendamist). Loomisel null.

400Päring on vigane: parameetri väärtus või objekti olek ei võimalda toimingut (`detail` on teade).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

409Objekti olek ei võimalda toimingut, näiteks duplikaat, käimasolev indekseerimine või juba töödeldud töö.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

  • Retry-After

    Sekundite arv, mida oodata enne päringu kordamist.

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← webhooks · API teatmik