REST API odpovídá na otázku jak můj systém čte platformu? Webhooky odpovídají na obrácenou: jak platforma řekne mému systému, že se něco stalo? Bez webhooků se integrace musí ptát opakovaně. Každých pár minut se probudí, zeptají se "je něco nového?" a většinou zní odpověď ne. To plýtvá výpočetním výkonem na obou stranách, vnáší prodlevu mezi událost a reakci na ni a s růstem počtu integrací se to špatně škáluje. S webhooky se z platformy stává zdroj událostí, na který navazující systémy reagují ve chvíli, kdy se něco stane – a tak by moderní integrace měly fungovat.
Na odchozí straně je odeslání webhooku prostě jen další krok automatizace. Akce odeslání webhooku spustí HTTP požadavek ve chvíli, kdy k ní automatizace dojde, a to s plnou kontrolou nad podobou požadavku: metoda (GET, POST, PUT, DELETE a další), hlavičky (statické, nebo řízené výrazy), tělo (libovolná struktura JSON poskládaná z kontextu automatizace) a parametry endpointu pro dynamické hodnoty v cestě a dotazu. Právě tahle pružnost dělá z akce použitelný nástroj pro reálné integrace – každý cílový systém má vlastní očekávání ohledně požadavků a akce webhooku jim umí vyhovět, aniž byste psali jakýkoli vlastní kód.
Parametry endpointu si zaslouží zvláštní zmínku. Automatizace spuštěná úpravou záznamu často potřebuje komunikovat se vzdáleným systémem pomocí identifikátorů z toho záznamu, který se právě upravuje. Místo ručního skládání URL ze zřetězených řetězců zpřístupní akce kontext automatizace přímo šabloně URL. /partners/{customer.partnerId}/sync se v okamžiku odeslání přirozeně vyhodnotí a doplní aktuální hodnoty ze záznamu. Totéž platí pro hlavičky i pro tělo JSON – jazyk vložených výrazů je k dispozici všude, kde dává dynamická hodnota smysl.
Vlastní očekávání ohledně stavových kódů HTTP jsou drobnost, která automatizacím postaveným na webhoocích pomáhá chovat se dobře. Různé vzdálené systémy mají různé zvyklosti kolem toho, co je úspěch a co selhání – některé vracejí na všechno 200, jiné používají 202 pro asynchronní přijetí, další 204 pro prázdnou odpověď a některé mají vlastní kódy. Akce vám dovolí určit, které kódy se počítají jako úspěch, které spustí opakování a které mají automatizaci zastavit. Při dočasných výpadcích proběhne opakování automaticky, s rozumným odstupem mezi pokusy.
Na příchozí straně obrátí vztah spouštěče webhooků. Automatizaci lze nastavit tak, aby se spustila, když externí systém pošle POST na URL specifickou pro dané prostředí. Příchozí požadavek – hlavičky, tělo, parametry dotazu – dostane automatizace jako kontext a zbytek tvůrce funguje úplně stejně: automatizace může vytvářet záznamy, posílat oznámení, spouštět další akce a odpovědět volajícímu. Takhle partnerské systémy oznamují platformě události, takhle veřejné formuláře na marketingových webech posílají odeslaná data dovnitř prostředí a takhle se starší systémy napojí na moderní tok.
Zvláštní varianta akce, prázdný endpoint, řeší opak plnohodnotného webhooku – prostý ping bez těla, který se hodí pro kontroly stavu, spouštění obnovy a signály typu "jsem tu pořád". Podobně je nastavitelná i odpověď, kterou spuštěná automatizace pošle zpět volajícímu, takže příchozí webhooky mohou vracet strukturovaná data, když volající odpověď očekává, místo aby jen odeslaly a zapomněly.
Autentizace mezi platformou a vzdálenými systémy se řeší přes hlavičky, což integrátorům dává přístup k celé škále autentizačních schémat: bearer tokeny, basic auth, podepsané požadavky, API klíče ve vlastních hlavičkách a cokoli dalšího, co vzdálený systém vyžaduje. Samotné přihlašovací údaje by měly být uložené ve správě citlivých údajů (má vlastní článek), ne vlepené do kroků automatizace – když se na citlivý údaj v hlavičce odkážete jménem, mění se na jednom místě, ne v každé automatizaci, která ho používá.
Zpracování odpovědi zachytí, co vzdálený systém vrátí, a zpřístupní to dalším krokům automatizace. Pokud volání externího API vrátí ID, potvrzení nebo kus dat, který automatizace potřebuje, tato hodnota přirozeně přeteče do dalšího kroku. Právě proto se akce webhooku může zapojit do vícekrokových pracovních postupů, místo aby byla slepou uličkou. Odeslat požadavek, použít odpověď k aktualizaci místního záznamu, poslat navazující oznámení: tři kroky v tvůrci, žádné vlastní lepení.
Opakování při dočasných výpadcích proběhne tam, kde je to nastaveno, automaticky, s odstupem, který respektuje očekávanou zátěž vzdáleného systému. Chyby se zapisují do protokolu s plným kontextem – odeslaný požadavek i vrácená odpověď –, takže má ten, kdo selhaný webhook zkoumá, k dispozici všechno potřebné k diagnóze. Když se trvalá selhání nakupí, umí vlastní cesta hlášení chyb v automatizaci (rozebírá ji článek o automatizacích) upozornit administrátory, spustit záložní postup nebo problematický záznam odložit stranou, dokud se na něj nepodívá člověk.
Protokolování požadavků je malý, ale užitečný detail pro ladění. Volání webhooků – jak odchozí požadavky, které platforma posílá, tak příchozí, které přijímá – se objeví v protokolu požadavků API, kde se dají zkoumat stejnými nástroji jako jakýkoli jiný provoz API. Právě tato jednotnost dělá z integrací postavených na webhoocích něco skutečně pozorovatelného, ne neprůhledného.
Ještě pár slov k návrhovým vzorům. Odeslat a zapomenout (fire-and-forget) je správná volba, když navazující systém nemusí odpovídat – zápis zákaznické události do analytické platformy, poslání oznámení do chatu, spuštění přeindexování na navazujícím systému. Požadavek a odpověď (request-response) je správná volba, když platforma potřebuje výstup vzdáleného systému, než bude pokračovat – služba pro ověření adresy, autorizační odpověď platební brány, externí generátor ID. Akce zvládá obojí stejně dobře. Co po vás nechce, je vybrat si mezi nimi na úrovni architektury: automatizace může oba vzorce podle potřeby kombinovat.
Webhooky dokreslují obraz integrací. S REST API integrace z platformy tahají data, s webhooky jim je platforma sama posílá. Dohromady umožňují stavět kolem prostředí opravdu událostmi řízené systémy – systémy, kde data i události proudí oběma směry, aniž by kdokoli musel psát lepicí kód, který by jinak spolykal celý rozpočet na integraci.