Webhook je zpráva, kterou Quanda sama pošle na adresu vašeho systému, když nastane událost, například klik na odkaz, otevření e-mailu, odhlášení, odeslání e-mailu nebo uložení vyplněného dotazníku. Webhooky spravujete v Quandě v Nastavení / Webhooky. Každý webhook může nést vlastní hlavičku s tajným tokenem, podle které váš systém ověří, že volání opravdu poslala Quanda.

Jak přidat a upravit webhook

Seznam webhooků najdete v Nastavení / Webhooky. V dialogu pro přidání a úpravu webhooku zadáte adresu, na kterou má Quanda volání posílat, a událost, při které se má webhook odeslat.

Dialog obsahuje také volitelná pole pro vlastní hlavičku:

  • Název hlavičky: název, pod kterým Quanda hodnotu k volání přidá, například X-Webhook-Token.
  • Hodnota hlavičky: tajný token, který váš systém porovná se svou uloženou hodnotou. U uloženého webhooku pole ukazuje jen masku.
  • Odebrat hlavičku: volba, která se zobrazuje u webhooku s hlavičkou. Po uložení Quanda hlavičku k volání přestane přidávat.

Obě pole můžete nechat prázdná. Webhook pak funguje stejně jako dosud.

Co znamená ikona zámku v seznamu webhooků

Ikona zámku v seznamu označuje webhook zabezpečený vlastní hlavičkou. Webhook bez zámku hlavičku nemá a Quanda ho volá bez ní.

Ověření původu volání vlastní hlavičkou

Hlavička je doplňující údaj HTTP požadavku ve tvaru název a hodnota, který se posílá spolu s voláním, ale není součástí jeho obsahu. Token je náhodný řetězec znaků, který znáte jen vy a Quanda, a slouží podobně jako heslo.

Volání webhooku bez hlavičky neobsahuje žádný údaj, podle kterého by příjemce poznal odesílatele. Kdokoli, kdo zná adresu, na ni může poslat podvržené volání. Vlastní hlavička tomu brání.

Jak to funguje

Quanda přidá nastavenou hlavičku ke každému volání webhooku. Váš systém hodnotu hlavičky porovná s hodnotou, kterou má uloženou, a volání zpracuje jen při shodě.

Jako token použijte náhodný řetězec o délce alespoň 32 znaků a nepoužívejte ho nikde jinde než pro Quandu. Volání bez správné hlavičky ve svém systému odmítněte odpovědí se stavem 401.

Obsah volání, tedy jeho tělo, se nemění. Funkce je volitelná a webhooky bez hlavičky fungují přesně jako dosud.

Jak hlavičku nastavit

  1. V Quandě otevřete Nastavení / Webhooky.
  2. Přidejte nový webhook nebo otevřete úpravu stávajícího.
  3. Zkontrolujte, že adresa webhooku začíná na https://.
  4. Do pole Název hlavičky napište název, například X-Webhook-Token.
  5. Do pole Hodnota hlavičky vložte tajný token.
  6. Webhook uložte. V seznamu se u něj zobrazí ikona zámku.

Token si uložte ve svém systému dřív, než webhook uložíte. Uloženou hodnotu už Quanda nikde nezobrazí.

Jak hlavičku změnit nebo odebrat

  • Úprava webhooku beze změny hlavičky: pole Hodnota hlavičky nechte prázdné. Hlavička zůstane tak, jak je uložená.
  • Změna tokenu: do pole Hodnota hlavičky zadejte novou hodnotu a webhook uložte. Nová hodnota platí od dalšího volání, proto ji ve stejnou chvíli změňte i ve svém systému.
  • Odebrání hlavičky: zvolte Odebrat hlavičku a webhook uložte. Ikona zámku ze seznamu zmizí.

Podmínky a omezení

  • Adresa na https://: protokol https přenáší data šifrovaně. Webhook s hlavičkou musí mít adresu začínající na https:// a cílový server musí mít platný certifikát. Na nešifrovanou adresu Quanda hlavičku nepošle.
  • Název hlavičky: smí obsahovat písmena, číslice a pomlčku a mít nejvýše 64 znaků. Hlavička Authorization je povolená. Některé technické názvy povolené nejsou, například Host, Content-Type, Cookie a názvy začínající na X-Quanda-.
  • Hodnota hlavičky: smí obsahovat tisknutelné znaky bez diakritiky a mít nejvýše 1024 znaků.
  • Počet hlaviček: v aplikaci nastavíte u webhooku jednu hlavičku, přes API až 5. Webhook s více hlavičkami nastavenými přes API pole pro hlavičku v aplikaci nezobrazuje a upravujete ho přes API.
  • Zobrazení hodnoty: uložená hodnota se v aplikaci ani v API nezobrazuje. Vidíte jen masku, tedy čtyři hvězdičky a poslední 4 znaky. U hodnot kratších než 12 znaků jsou vidět jen hvězdičky.

Jak Quanda webhooky doručuje

Váš systém má na volání odpovědět stavem 200. Při jiné odpovědi Quanda volání zopakuje, a to až 5krát:

  1. po 30 sekundách,
  2. po 5 minutách,
  3. po 50 minutách,
  4. přibližně po 8 hodinách,
  5. přibližně po 83 hodinách.

Stejně Quanda postupuje, když váš systém odmítne volání kvůli hlavičce. Vlastní hlavička doručování nemění.

Dokumentace pro vývojáře

Webhooky můžete vytvářet a upravovat i přes API. Hlavičky se nastavují v poli headers při vytvoření a úpravě webhooku, tedy ve voláních POST, PUT a PATCH na /api/webhook/webhooks/. Úprava webhooku beze změny voláním PUT už nevrací chybu a částečná úprava voláním PATCH nevyžaduje pole event.

Popis všech volání a struktury zpráv najdete v API dokumentaci, části Webhooky. Jak získat API klíč, popisuje článek Dokumentace k API a API klíč.

Vlastní hlavička je dostupná bez příplatku všem účtům, které mají přístup k Nastavení / Webhooky a k API.

Máte otázky? Rádi Vám na ně odpovíme. Stačí kontaktovat naši zákaznickou podporu na tel. +420 605 163 892, e-mail: support@onquanda.com.

Časté otázky

Ne, vlastní hlavička je volitelná. Webhooky bez hlavičky fungují přesně jako dosud, včetně adres začínajících na http://.

Nikde. V aplikaci i v API se zobrazuje jen maska, tedy čtyři hvězdičky a poslední 4 znaky, u hodnot kratších než 12 znaků jen hvězdičky. Token si proto uložte ve svém systému dřív, než webhook uložíte.

Adresa na http:// není šifrovaná a Quanda na ni hlavičku s tajnou hodnotou nepošle. Webhook s hlavičkou proto musí mít adresu začínající na https:// a cílový server platný certifikát.

Webhook má více hlaviček nastavených přes API. V aplikaci lze nastavit jednu hlavičku, takový webhook proto upravujete přes API.

Quanda čeká odpověď se stavem 200. Při jiné odpovědi volání zopakuje až 5krát. Zkontrolujte, že váš systém porovnává hlavičku se stejnou hodnotou, jakou jste uložili v Quandě.