Preskočiť na obsah
Sursa Developers

POST/v1/webhooks

Vytvoriť webhook

create_webhook

URL musí používať https a jej hostiteľ sa musí prekladať na verejné adresy. Súkromné siete (RFC 1918), loopback, link-local, siete metadátových služieb cloudu a ďalšie siete na špeciálne účely sa odmietajú pri registrácii aj pri každom pripojení. Tajný kľúč podpisu sa zobrazí raz v odpovedi (secret); potom ho možno už len vymeniť. Organizácia môže mať najviac 20 webhookov.

Odber obsahuje typy udalostí a masky domén (card.*, *). Prístup sa nastavuje rovnako ako pri kľúči API: role, data_profile_id a collection_ids. Udalosť o objekte, ktorý rola, dátový profil alebo kolekcie nevidia, sa nedoručí. tags obmedzia udalosti kariet na karty s ktorýmkoľvek zo štítkov. payload: thin posiela udalosti bez data. Vlastné hlavičky (headers) a odchádzajúca autorizácia (auth) sa ukladajú zašifrované; odpovede obsahujú len názvy hlavičiek a príznaky value_set a auth_set.

Autentifikácia

Odošlite kľúč API v hlavičke Authorization: Authorization: Bearer <kľúč>.

Parametre hlavičky

  • Idempotency-Keystring

    Kľúč na bezpečné opakovanie zápisu: 1 až 255 tlačiteľných znakov ASCII; odporúča sa UUID v4 pre každú logickú operáciu. Opakovanie s tým istým kľúčom do 24 hodín operáciu znova nespustí: vráti uloženú odpoveď (stav, hlavičky a telo) s hlavičkou Idempotency-Replayed: true. Ten istý kľúč s inou metódou, cestou, Content-Type alebo telom vráti 409 api.idempotency_mismatch; kým prvá požiadavka ešte prebieha, vráti 409 api.idempotency_in_progress s Retry-After: 1. Po odpovedi 5xx alebo 429 sa kľúč uvoľní a opakovanie operáciu spustí znova. Kľúč platí v rámci organizácie a volajúceho (kľúč API, používateľ alebo kľúč vlastného zdroja).

    length ≥ 1, length ≤ 255

Telo požiadavky

application/json

Objekt: WebhookCreate

  • urlstringpovinné

    URL príjemcu, len https://, najviac 2048 znakov.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterpovinné

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    Kolekcie, o ktorých webhook dostáva udalosti. Chýbajúca hodnota alebo prázdny zoznam znamená všetky kolekcie dostupné pre rolu a dátový profil. Kľúč, ktorý je sám obmedzený na kolekcie, vytvorí webhook len s neprázdnym zoznamom svojich vlastných kolekcií. Bez tohto poľa, s prázdnym zoznamom alebo s kolekciou mimo jeho zoznamu požiadavka vráti 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

Odpovede

201Vytvorené. Toto je jediný raz, keď sa `secret` zobrazí.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

  • Idempotency-Replayed

    true znamená, že odpoveď bola zopakovaná z uloženej odpovede pre tento Idempotency-Key: operácia sa znova nespustila.

application/json

Objekt: WebhookCreated

  • idintegerpovinné
  • urlstringpovinné
  • descriptionstringpovinné
  • eventsarray of WebhookEventFilterpovinné
  • activebooleanpovinné
  • statusWebhookStatuspovinné
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: 10 neúspešných pokusov za sebou; feature_disabled: tarifa nezahŕňa webhooky.

  • disabled_reasonstring | null

    gone: príjemca odpovedal 410; manual: vypnuté administrátorom.

    Povolené hodnoty: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRolepovinné
  • data_profile_idinteger | null

    Dátový profil webhooku (null znamená bez profilu, ako pri kľúči API s rovnakou rolou).

  • collection_idsarray of integerpovinné

    Kolekcie, o ktorých webhook dostáva udalosti; prázdne znamená všetky kolekcie dostupné pre rolu a dátový profil.

  • tagsarray of stringpovinné

    Udalosti kariet len pre karty s niektorým z týchto štítkov; prázdne znamená bez filtra.

  • payloadWebhookPayloadModepovinné
  • headersarray of WebhookHeaderpovinné
  • auth_typestring | null

    Typ odchádzajúcej autorizácie (null znamená žiadna).

    Povolené hodnoty: bearerbasicnull

  • auth_setbooleanpovinné

    Či je odchádzajúca autorizácia nastavená (hodnoty sa nikdy nevracajú).

  • previous_secret_valid_untilstring (date-time) | null

    Dokedy sa doručenia podpisujú aj predchádzajúcim tajným kľúčom (null znamená, že prekryv nie je).

  • healthWebhookHealth
  • consecutive_failuresintegerpovinné
  • 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)povinné
  • updated_atstring (date-time)povinné
  • secretstringpovinné

    whsec_ a za ním 32 bajtov v base64 (nové tajné kľúče používajú štandardnú abecedu s doplnením, staršie base64url). Uložte ho na strane príjemcu; v odpovediach API sa už nikdy neobjaví. Podpisový kľúč Standard Webhooks je base64 dekódovaná časť za whsec_.

  • previous_valid_untilstring (date-time) | null

    Dokedy sa predchádzajúci tajný kľúč ešte prijíma (po výmene). Pri vytvorení null.

400Požiadavka je neplatná: hodnota parametra alebo stav objektu akciu nedovoľuje (`detail` je správa).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

401Neboli odoslané žiadne prihlasovacie údaje (ani cookie relácie, ani kľúč API) alebo sa kľúč nenašiel.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

403Akcia nie je povolená: rola nestačí, chýba prístup ku kolekcii alebo karte, požiadavka beží v režime „View as“ alebo je organizácia pozastavená či odstránená (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

409Stav objektu akciu nedovoľuje, napríklad duplicita, prebiehajúce indexovanie alebo úloha, ktorá je už spracovaná.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

422Chyba validácie: telo alebo parametre nezodpovedajú schéme (`detail` je zoznam chýb validácie) alebo je hodnota parametra mimo rozsahu (`detail` je správa).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

429Príliš veľa požiadaviek (`api.rate_limited`), vyčerpaná kvóta organizácie na minútu, deň alebo mesiac (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), dosiahnutý limit organizácie alebo zaneprázdnená služba odpovedí (`answers.engine_busy`). Počkajte čas uvedený v hlavičke `Retry-After`.

Hlavičky odpovede

  • Retry-After

    Počet sekúnd, ktoré treba počkať pred opakovaním požiadavky.

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, ktoré táto operácia môže vrátiť v error.code, okrem všeobecných kódov každej požiadavky.

Bezpečné opakovanie

S každou požiadavkou POST a PATCH odošlite hlavičku Idempotency-Key (napríklad UUID). Opakovaná požiadavka s rovnakým kľúčom do 24 hodín vráti uloženú odpoveď namiesto toho, aby sa požiadavka vykonala znova.

Limity frekvencie

Odpovede obsahujú hlavičky RateLimit a RateLimit-Policy a staršie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpoveď 429 má hlavičku Retry-After v sekundách: počkajte a požiadavku zopakujte.

← webhooks · Referencia API