PATCH/v1/webhooks/{webhook_id}

Upraviť webhook

update_webhook

Zmení URL, popis, odbery, prístup, filtre, vlastné hlavičky, odchádzajúcu autorizáciu a stav zapnutia. active: true webhook zapne a zruší pozastavenie, takže nahromadené doručenia sa odošlú v poradí. active: false webhook vypne a zruší čakajúce doručenia. headers nahradí celý zoznam vlastných hlavičiek; položka bez value si ponechá predchádzajúcu hodnotu hlavičky s rovnakým názvom. auth: null a data_profile_id: null odstránia odchádzajúcu autorizáciu a dátový profil.

Autentifikácia

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

Parametre cesty

webhook_idintegerpovinné

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: WebhookUpdate

urlstring | null
length ≤ 2048
descriptionstring | null
length ≤ 200
eventsarray of WebhookEventFilter | null
items ≥ 1
activeboolean | null
rolestring | null
Povolené hodnoty: admineditorviewernull
data_profile_idinteger | null
null odstráni dátový profil.
collection_idsarray of integer | null
Kolekcie webhooku. Prázdny zoznam znamená všetky kolekcie dostupné pre rolu a dátový profil; chýbajúca hodnota alebo null ich ponechá bez zmeny. Kľúč, ktorý je sám obmedzený na kolekcie, vidí a mení len webhooky, ktorých kolekcie sú v jeho zozname (ostatné webhooky vrátia 404 webhooks.not_found). Prázdny zoznam alebo kolekcia mimo jeho zoznamu vráti 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string | null
items ≤ 50
payloadstring | null
Povolené hodnoty: fullthinnull
headersarray of WebhookHeaderInput | null
items ≤ 10
authWebhookAuthInput | null
null odstráni odchádzajúcu autorizáciu.

Odpovede

200Úspešná odpoveď

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: WebhookEndpoint

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é

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

404Objekt neexistuje alebo vám nie je dostupný. API nepotvrdzuje, že objekt s obmedzeným prístupom existuje.

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

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

Vyskúšať

Kľúč API

Kľúč zostáva v pamäti tejto karty prehliadača a odosiela sa len na https://api.sursa.com.

Požiadavky pracujú so skutočnými údajmi vašej organizácie.

Idempotency-Key header

webhook_id path *

Idempotency-Key

Ak je pole prázdne, pre každú požiadavku sa vygeneruje nový kľúč.

Telo požiadavky (JSON)