Webhook je správa, ktorú Quanda sama pošle na adresu vášho systému, keď nastane udalosť, napríklad klik na odkaz, otvorenie e-mailu, odhlásenie, odoslanie e-mailu alebo uloženie vyplneného dotazníka. Webhooky spravujete v Quande v Nastaveniach / Webhooky. Každý webhook môže niesť vlastnú hlavičku s tajným tokenom, podľa ktorej váš systém overí, že volanie naozaj poslala Quanda.

Ako pridať a upraviť webhook

Zoznam webhookov nájdete v Nastaveniach / Webhooky. V dialógu na pridanie a úpravu webhooku zadáte adresu, na ktorú má Quanda volania posielať, a udalosť, pri ktorej sa má webhook odoslať.

Dialóg obsahuje aj voliteľné polia pre vlastnú hlavičku:

  • Názov hlavičky: názov, pod ktorým Quanda hodnotu k volaniu pridá, napríklad X-Webhook-Token.
  • Hodnota hlavičky: tajný token, ktorý váš systém porovná so svojou uloženou hodnotou. Pri uloženom webhooku pole ukazuje len masku.
  • Odstrániť hlavičku: voľba, ktorá sa zobrazuje pri webhooku s hlavičkou. Po uložení Quanda hlavičku k volaniu prestane pridávať.

Obe polia môžete nechať prázdne. Webhook potom funguje rovnako ako doteraz.

Čo znamená ikona zámku v zozname webhookov

Ikona zámku v zozname označuje webhook zabezpečený vlastnou hlavičkou. Webhook bez zámku hlavičku nemá a Quanda ho volá bez nej.

Overenie pôvodu volania vlastnou hlavičkou

Hlavička je doplňujúci údaj HTTP požiadavky v tvare názov a hodnota, ktorý sa posiela spolu s volaním, ale nie je súčasťou jeho obsahu. Token je náhodný reťazec znakov, ktorý poznáte len vy a Quanda, a slúži podobne ako heslo.

Volanie webhooku bez hlavičky neobsahuje žiadny údaj, podľa ktorého by príjemca spoznal odosielateľa. Ktokoľvek, kto pozná adresu, na ňu môže poslať podvrhnuté volanie. Vlastná hlavička tomu bráni.

Ako to funguje

Quanda pridá nastavenú hlavičku ku každému volaniu webhooku. Váš systém hodnotu hlavičky porovná s hodnotou, ktorú má uloženú, a volanie spracuje len pri zhode.

Ako token použite náhodný reťazec s dĺžkou aspoň 32 znakov a nepoužívajte ho nikde inde ako pre Quandu. Volania bez správnej hlavičky vo svojom systéme odmietnite odpoveďou so stavom 401.

Obsah volania, teda jeho telo, sa nemení. Funkcia je voliteľná a webhooky bez hlavičky fungujú presne ako doteraz.

Ako hlavičku nastaviť

  1. V Quande otvorte Nastavenia / Webhooky.
  2. Pridajte nový webhook alebo otvorte úpravu existujúceho.
  3. Skontrolujte, že adresa webhooku začína na https://.
  4. Do poľa Názov hlavičky napíšte názov, napríklad X-Webhook-Token.
  5. Do poľa Hodnota hlavičky vložte tajný token.
  6. Webhook uložte. V zozname sa pri ňom zobrazí ikona zámku.

Token si uložte vo svojom systéme skôr, ako webhook uložíte. Uloženú hodnotu už Quanda nikde nezobrazí.

Ako hlavičku zmeniť alebo odstrániť

  • Úprava webhooku bez zmeny hlavičky: pole Hodnota hlavičky nechajte prázdne. Hlavička zostane tak, ako je uložená.
  • Zmena tokenu: do poľa Hodnota hlavičky zadajte novú hodnotu a webhook uložte. Nová hodnota platí od ďalšieho volania, preto ju v rovnakej chvíli zmeňte aj vo svojom systéme.
  • Odstránenie hlavičky: zvoľte Odstrániť hlavičku a webhook uložte. Ikona zámku zo zoznamu zmizne.

Podmienky a obmedzenia

  • Adresa na https://: protokol https prenáša dáta šifrovane. Webhook s hlavičkou musí mať adresu začínajúcu na https:// a cieľový server musí mať platný certifikát. Na nešifrovanú adresu Quanda hlavičku nepošle.
  • Názov hlavičky: smie obsahovať písmená, číslice a spojovník a mať najviac 64 znakov. Hlavička Authorization je povolená. Niektoré technické názvy povolené nie sú, napríklad Host, Content-Type, Cookie a názvy začínajúce na X-Quanda-.
  • Hodnota hlavičky: smie obsahovať tlačiteľné znaky bez diakritiky a mať najviac 1024 znakov.
  • Počet hlavičiek: v aplikácii nastavíte pri webhooku jednu hlavičku, cez API až 5. Webhook s viacerými hlavičkami nastavenými cez API polia pre hlavičku v aplikácii nezobrazuje a upravujete ho cez API.
  • Zobrazenie hodnoty: uložená hodnota sa v aplikácii ani v API nezobrazuje. Vidíte len masku, teda štyri hviezdičky a posledné 4 znaky. Pri hodnotách kratších ako 12 znakov sú viditeľné len hviezdičky.

Ako Quanda webhooky doručuje

Váš systém má na volanie odpovedať stavom 200. Pri inej odpovedi Quanda volanie zopakuje, a to až 5-krát:

  1. po 30 sekundách,
  2. po 5 minútach,
  3. po 50 minútach,
  4. približne po 8 hodinách,
  5. približne po 83 hodinách.

Rovnako Quanda postupuje, keď váš systém odmietne volanie pre hlavičku. Vlastná hlavička doručovanie nemení.

Dokumentácia pre vývojárov

Webhooky môžete vytvárať a upravovať aj cez API. Hlavičky sa nastavujú v poli headers pri vytvorení a úprave webhooku, teda vo volaniach POST, PUT a PATCH na /api/webhook/webhooks/. Úprava webhooku bez zmeny volaním PUT už nevracia chybu a čiastočná úprava volaním PATCH nevyžaduje pole event.

Opis všetkých volaní a štruktúry správ nájdete v angličtine v API dokumentácii, časti Webhooks. Ako získať API kľúč, opisuje článok Dokumentácia k API a API kľúč.

Vlastná hlavička je dostupná bez príplatku všetkým účtom, ktoré majú prístup k Nastaveniam / Webhooky a k API.

Ak si neviete rady alebo máte otázku, neváhajte kontaktovať našu zákaznícku podporu na support@onquanda.com alebo na telefóne +420 605 163 892.

Časté otázky

Nie, vlastná hlavička je voliteľná. Webhooky bez hlavičky fungujú presne ako doteraz, vrátane adries začínajúcich na http://.

Nikde. V aplikácii aj v API sa zobrazuje len maska, teda štyri hviezdičky a posledné 4 znaky, pri hodnotách kratších ako 12 znakov len hviezdičky. Token si preto uložte vo svojom systéme skôr, ako webhook uložíte.

Adresa na http:// nie je šifrovaná a Quanda na ňu hlavičku s tajnou hodnotou nepošle. Webhook s hlavičkou preto musí mať adresu začínajúcu na https:// a cieľový server platný certifikát.

Webhook má viac hlavičiek nastavených cez API. V aplikácii sa dá nastaviť jedna hlavička, taký webhook preto upravujete cez API.

Quanda čaká odpoveď so stavom 200. Pri inej odpovedi volanie zopakuje až 5-krát. Skontrolujte, že váš systém porovnáva hlavičku s rovnakou hodnotou, akú ste uložili v Quande.