Přejít na obsah
Sursa Developers

POST/v1/webhooks

Vytvořit webhook

create_webhook

URL musí používat https a její hostitel se musí překládat na veřejné adresy. Privátní sítě (RFC 1918), loopback, link-local, metadata cloudu a další sítě se zvláštním určením se odmítají při registraci i při každém připojení. Tajný klíč podpisu se zobrazí jednou v odpovědi (secret); poté ho lze jen obměnit. Organizace může mít nejvýše 20 webhooků.

Odběr uvádí typy událostí a masky domén (card.*, *). Přístup se nastavuje stejně jako u klíče API: role, data_profile_id a collection_ids. Událost o objektu, který role, datový profil nebo kolekce nevidí, se nedoručí. tags omezí události karet na karty s některým ze štítků. payload: thin odesílá události bez data. Vlastní hlavičky (headers) a autorizace odchozích požadavků (auth) se ukládají zašifrované; odpovědi obsahují jen názvy hlaviček a příznaky value_set a auth_set.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

  • Idempotency-Keystring

    Klíč pro bezpečné opakování zápisu: 1 až 255 tisknutelných znaků ASCII; doporučuje se UUID v4 pro každou logickou operaci. Opakování se stejným klíčem do 24 hodin operaci znovu nespustí: vrátí uloženou odpověď (stav, hlavičky a tělo) s hlavičkou Idempotency-Replayed: true. Stejný klíč s jinou metodou, cestou, Content-Type nebo tělem vrací 409 api.idempotency_mismatch; dokud první požadavek ještě běží, vrací 409 api.idempotency_in_progress s Retry-After: 1. Po odpovědi 5xx nebo 429 se klíč uvolní a opakování operaci spustí znovu. Klíč platí v rámci organizace a volajícího (klíč API, uživatel nebo klíč vlastního zdroje).

    length ≥ 1, length ≤ 255

Tělo požadavku

application/json

Objekt: WebhookCreate

  • urlstringpovinné

    URL příjemce, jen https://, nejvýše 2048 znaků.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterpovinné

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    Kolekce, o kterých webhook dostává události. Chybějící hodnota nebo prázdný seznam znamená všechny kolekce dostupné roli a datovému profilu. Klíč, který je sám omezen na kolekce, vytvoří webhook jen s neprázdným seznamem svých vlastních kolekcí. Bez tohoto pole, s prázdným seznamem nebo s kolekcí mimo jeho seznam vrací požadavek 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

Odpovědi

201Vytvořeno. Jen v této odpovědi se zobrazí `secret`.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

  • Idempotency-Replayed

    true znamená, že jde o znovu vrácenou uloženou odpověď pro tento Idempotency-Key: operace se znovu nespustila.

application/json

Objekt: WebhookCreated

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

    failures: 10 neúspěšných pokusů za sebou; feature_disabled: tarif nezahrnuje webhooky.

  • disabled_reasonstring | null

    gone: příjemce odpověděl 410; manual: vypnuto administrátorem.

    Povolené hodnoty: gonemanualnull

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

    Datový profil webhooku (null znamená bez profilu, stejně jako u klíče API se stejnou rolí).

  • collection_idsarray of integerpovinné

    Kolekce, o kterých webhook dostává události; prázdné znamená všechny kolekce dostupné roli a datovému profilu.

  • tagsarray of stringpovinné

    Události karet jen u karet s některým z těchto štítků; prázdné znamená bez filtru.

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

    Typ odchozí autorizace (null znamená žádná).

    Povolené hodnoty: bearerbasicnull

  • auth_setbooleanpovinné

    Zda je odchozí autorizace nastavena (hodnoty se nikdy nevracejí).

  • previous_secret_valid_untilstring (date-time) | null

    Do kdy se doručení podepisují i předchozím tajným klíčem (null znamená, že překryv neexistuje).

  • 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 bajtů v base64 (nové tajné klíče používají standardní abecedu s doplněním, starší base64url). Uložte ho na straně příjemce; v odpovědích API se už nikdy neobjeví. Podpisový klíč Standard Webhooks je base64 dekódování části za whsec_.

  • previous_valid_untilstring (date-time) | null

    Do kdy se předchozí tajný klíč ještě přijímá (po obměně). Při vytvoření null.

400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

409Stav objektu akci neumožňuje, například kvůli duplicitě, probíhajícímu indexování nebo úloze, která už je zpracovaná.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← webhooks · Reference API