Webhooky: jak poslat upozornění do jiné aplikace

Webhook je automatická zpráva, kterou web pošle jiné aplikaci, jakmile se něco stane. Například když přijde objednávka, když zveřejníte článek nebo když někdo odešle formulář. Díky tomu se může objednávka sama propsat do účetnictví nebo poptávka do CRM, tedy programu na evidenci zákazníků.

Webhooky obvykle nastavuje programátor nebo člověk, který propojuje aplikace. Hodí se i pro služby jako Make nebo Zapier. V nich si propojení poskládáte bez programování.

Kde webhooky najdete

Klikněte v horní liště na Konfigurace webu › Webhooky. Nahoře je tlačítko Nové napojení a počty doručených a nedoručených zpráv za posledních 24 hodin. Pod tím je seznam Napojení a Log doručení, tedy záznam všech odeslaných zpráv.

Pokud nahoře vidíte hlášku Webhooky nejsou ve vašem tarifu, napojení si připravit můžete, ale zprávy se odesílat nebudou. Tarif změníte v uživatelském menu pod položkou Předplatné. Více v článku Předplatné a objednávka tarifu.

Co budete potřebovat

Od aplikace, kam mají zprávy chodit, potřebujete adresu pro příjem webhooků. Vypadá například takto: https://hook.eu1.make.com/abc123. V aplikaci Make ji dostanete v modulu Webhooks, v jiných aplikacích vám ji dá programátor.

Adresa musí začínat https:// a musí být dostupná z internetu. Adresy ve firemní síti nebo na vlastním počítači systém odmítne.

Jak založit nové napojení

1. Klikněte na Nové napojení. Otevře se okno.
2. Do pole Název napište, kam zprávy jdou. Například Fakturace přes Make.
3. Do pole Cílová adresa vložte adresu od aplikace.
4. V části Události zaškrtněte, o čem chcete dostávat zprávy. Odkazem vybrat vše zaškrtnete celou skupinu.
5. V poli Obsah zprávy nechte Minimální. Pro účetnictví zvolte Celý objekt. Vysvětlení je níže.
6. Nechte zaškrtnuté Aktivní a klikněte na Uložit.
7. Ukáže se Podpisový klíč. Zkopírujte ho a pošlete programátorovi. Podruhé ho už neuvidíte. Pak klikněte na Mám uloženo.

Podpisový klíč slouží k ověření, že zpráva opravdu přišla z vašeho webu. Přijímající aplikace ho použije ke kontrole každé zprávy. Bez něj by jí mohl poslat falešnou zprávu kdokoli. Jak se podpis ověřuje, je ve třech krocích popsané přímo v okně s klíčem. Tento popis předejte programátorovi spolu s klíčem.

Na jaké události můžete reagovat

Pár věcí, které je dobré vědět:

• Události článků platí i pro stránky.
• Zprávy chodí jen o zveřejněném obsahu. Úpravy článků v přípravě se neposílají.
• Formuláře označené jako spam se neposílají.
• Změna stavu objednávky přijde při každé změně stavu. Když ji zaškrtnete spolu s Objednávka zaplacena, dostanete o zaplacení dvě zprávy. Zvolte buď jen změnu stavu, nebo jen konkrétní události.
• Při přenosu obsahu z jiného webu se zprávy o článcích neposílají. Jinak by aplikace dostala tisíce zpráv najednou.

Minimální zpráva, nebo celý objekt?

• Minimální: zpráva obsahuje jen číslo, název, adresu a odkaz, kde si aplikace zjistí aktuální údaje. Je to doporučená volba. Aplikace si data dotáhne přes API, a proto potřebuje API klíč.
• Celý objekt: u objednávek zpráva obsahuje i položky, ceny, DPH a adresy. Hodí se pro napojení na účetnictví, kde nechcete řešit API klíč.

Odeslaný formulář nese vyplněná pole vždy, v obou režimech. Jak vytvořit API klíč, popisuje článek API klíče: jak dát jiné aplikaci přístup k webu.

Jak napojení otestovat

1. V seznamu Napojení klikněte u napojení na Test.
2. Web hned pošle na adresu zkušební zprávu.
3. Výsledek uvidíte v Logu doručení. Stav doručeno znamená, že aplikace zprávu přijala.

Úpravy, vypnutí a smazání napojení

U každého napojení najdete tato tlačítka:

• Upravit: změníte název, adresu, události nebo obsah zprávy.
• Vypnout a Zapnout: dočasně zastaví posílání zpráv. Napojení zůstane uložené.
• Rotovat klíč: vytvoří nový podpisový klíč. Použijte ho, když se starý klíč mohl dostat k někomu cizímu. Předchozí klíč platí dál, aby napojení nepřestalo fungovat. U napojení pak uvidíte Platí i předchozí klíč (rotace). Postup je níže.
• Smazat: napojení odstraní.

Jak vyměnit podpisový klíč a zneplatnit ten starý

1. U napojení klikněte na Rotovat klíč a potvrďte dotaz.
2. Ukáže se nový Podpisový klíč. Zkopírujte ho, pošlete programátorovi a klikněte na Mám uloženo.
3. Počkejte, až programátor nový klíč nastaví v přijímající aplikaci. Do té doby platí oba klíče a zprávy chodí dál.
4. U napojení klikněte na odkaz Zneplatnit předchozí klíč pod textem Platí i předchozí klíč (rotace) a potvrďte dotaz.

Od té chvíle platí jen nový klíč. Starý klíč už nikdo nemůže zneužít. Když na poslední krok zapomenete, starý klíč bude platit dál.

Log doručení: jak zjistit, jestli zprávy chodí

V části Log doručení je každá odeslaná zpráva. Filtrovat můžete podle stavu, napojení a události. Tlačítkem Obnovit načtete nové záznamy.

• doručeno: aplikace zprávu přijala.
• ve frontě: zpráva čeká na odeslání. Odchází obvykle do minuty.
• čeká na další pokus: aplikace zprávu nepřijala. Web to zkusí znovu za minutu, pak za 5 minut, za 15 minut, za hodinu a za 6 hodin.
• selhalo natrvalo: ani poslední pokus nevyšel. Zprávu můžete poslat znovu ručně.
• přeskočeno: zpráva se neposlala. Například když bylo napojení mezitím vypnuté nebo smazané.

Tlačítkem Detail u záznamu otevřete okno Detail doručení. Uvidíte, co web poslal a co aplikace odpověděla. Tlačítkem Odeslat znovu zprávu pošlete ještě jednou. Obsah zpráv se z logu maže po 7 dnech, celé záznamy po 30 dnech.

Napojení má stav automaticky vypnuto

Když aplikace 20 zpráv za sebou nepřijme, web napojení sám vypne. Správcům webu přijde e-mail. Chrání to web před zbytečným posíláním na nefunkční adresu.

1. V logu doručení se podívejte, co aplikace odpovídala.
2. Opravte chybu. Obvykle je špatně adresa nebo aplikace neběží.
3. U napojení klikněte na Zapnout.
4. Klikněte na Test a zkontrolujte, že zpráva prošla.

Aplikace musí odpovědět do 10 sekund. Pomalejší odpověď web počítá jako nedoručení. Pokud to programátor potřebuje vědět, řekněte mu to.