Webhooky: Propojení SuperSaaS s ostatními weby
Webhooky jsou uživatelem definované funkce (callbacky), pomocí kterých lze ostatním aplikacím a webům posílat v reálném čase informace o událostech, které na vašem účtu nastanou.
Příklady použití webhooků:
- Přihlášení uživatele do seznamu adresátů ve službě MailChimp při registraci v rámci určitého účtu SuperSaaS
- Odeslání PDF souboru s obchodními podmínkami e-mailem uživateli, který se právě zaregistroval
- Vygenerování faktury v QuickBooks nebo Freshbooks, jakmile je vytvořena rezervace
- Jakmile se někdo přihlásí na určitý vyučovací předmět, bude provedeno označení v Google Kalendáři lektora této třídy
- Odeslání notifikace na Slack nebo do telefonu chvilku předtím, než začne schůzka
- Jakmile je uživatel přesunut z čekací listiny na potvrzené místo, bude mu zaslána SMS zpráva
- Přesměrování odeslaných e-mailů na Odesílání emailů přes jiný emailový server
Automatické nastavení webhooků pomocí služeb Zapier.com nebo Make
Pomocí služeb Zapier.com a Make.com lze interaktivně propojovat stovky známých služeb, včetně SuperSaaS, bez jakékoliv znalosti programování. Zapier i Make nabízejí zkušební verze i bezplatné verze pro drobné uživatele.
Díky již hotovým příkladům by mělo být vytváření webhooků poměrně jednoduché. Informace o podrobnějším nastavení a filtrování pouze některých událostí naleznete níže.
Nový uživatel do mailing listu na MailChimpu
Nová rezervace do Google Kalendáře
Nová rezervace vytvoří fakturu v QuickBooks
Nová rezervace do e-mailového filtruPodporované triggery
Existuje několik událostí, které lze sledovat. U některých entit lze sledovat událost „new“ (nový) nebo „change“ (změna). Událost „change“ zahrnuje všechny změny, takže se spustí i při událostech „new“ a „delete“ (odstranění). Pokud tedy nastavíte „Nový uživatel“ i „Změna uživatele“, spustí se při registraci uživatele oba webhooky. Pozor na situaci, kdy nastavíte, že rozvrh nevyžaduje registraci – v tom případě se nikdy nespustí trigger „Nový uživatel“, spustí se pouze „Nová rezervace“.
| Trigger | Spustí se při… |
|---|---|
| Nový uživatel | Spustí se při registraci uživatele na vašem účtu |
| Změna uživatele | Spustí se, když si uživatel upraví své údaje nebo když za něj údaje upraví administrátor. |
| Nová rezervace | Spustí se, když uživatel nebo administrátor vytvoří rezervaci v konkrétním rozvrhu. |
| Změna rezervace | Spustí se při jakékoliv změně rezervace, včetně „Nová“, „Odstranění“, „Umístění z čekací listiny“, „Platba přijata“ atd. (Celý seznam naleznete níže) |
| Nový formulář | Spustí se, když je vyplněn samostatný formulář. Nespustí se u formulářů, které jsou připojeny k rezervacím – v takovém případě se spustí webhook pro rezervaci. |
| Změněný formulář | Spustí se při jakékoliv změně samostatného formuláře (integrovaný formulář spustí triggery „Změna rezervace“ nebo „Změna uživatele“) |
| Odeslat e-mail | Spustí se při odesílání e-mailů z vašeho účtu, včetně e-mailů pro „Zapomenuté heslo“ atd. To lze využít pro odesílání e-mailů z vlastního serveru. Pokud je tento webhook aktivní, e-maily se nebudou odesílat ze serverů SuperSaaS. |
| Připomínka Follow-up | Spouští se při připomínkách a follow-upech. Pokud je tento webhook aktivní, e-maily s připomínkami nebo follow-upy se nebudou odesílat ze serverů SuperSaaS. |
Filtrování událostí
Jakmile v Zapieru nebo Make propojíte dvě služby, budete mít možnost události filtrovat. Zde je pár příkladů, jak lze filtrování využít:
- Posílat SMS pouze při umístění z čekací listiny, ne při každé změně rezervace
- Při vytvoření rezervace odeslat připomínku lektorovi, pouze pokud jde o jeho předmět, ostatní rezervace na stejném rozvrhu ignorovat
- Odeslat připomínku vedení firmy pouze u rezervací přesahujících 2 000 Kč
Při vytváření webhooku si Zapier/Make vyžádá ze SuperSaaS ukázkový objekt. Ukázkový objekt obsahuje všechna dostupná pole a příklady použití. To, která pole webhook odešle, závisí na tom, která pole máte na účtu povolená a zda je připojen vlastní formulář. U většiny triggerů jsou k dispozici pole „event“ (událost) a „role“ (role), která lze použít pro filtrování. Můžete například filtrovat pouze triggery, které mají v poli „event“ hodnotu „delete“.
| Trigger | Možné hodnoty v poli „event“ |
|---|---|
| Nový uživatel | new |
| Změna uživatele | new, change, delete |
| Nová rezervace | create |
| Změna rezervace | create, edit, place, pending, destroy, restore, approve, revert |
| Nový formulář | new |
| Změna formuláře | new, change, delete, restore |
| Připomínka / Follow-up | reminder, follow_up |
| Pole „role“ | Kým je událost spuštěna… | |
|---|---|---|
| 0 | Anonymní | Nepřihlášený |
| 1 | Přihlášený se sdíleným heslem | |
| 2 | Uživatel ověřený pomocí IP rozsahu | |
| 3 | Běžný uživatel | |
| 4 | Superuživatel | |
| 5 | Administrátor nebo přeprodejce | |
| 7 | Systém nebo platební brána | |
Při vytváření nebo změně rezervace obsahující platbu naleznete v polích „status“ (stav) a „status message“ (stavová zpráva) podrobnosti události – celý seznam stavů naleznete v sekci stavové kódy. Můžete tak například vytvořit filtr, kterým projdou pouze události, které byly refundovány.
Ruční nastavení webhooků (pokročilé)
Tato funkce je k dispozici pouze pro platící zákazníky. Můžete si ji vyzkoušet na týden kliknutím na tlačítko „Začátek zkoušky zdarma“ na obrazovce s webhooky.
Vytváření webhooků bez použití Zapieru nebo Make vyžaduje určité vývojářské dovednosti. Zbytek této stránky obsahuje informace pro programátory, kteří mohou přidat webhook pro odesílání informací do jejich aplikace nebo kteří chtějí naprogramovat vlastní rozhraní mezi SuperSaaS a jiným webem.
Webhooky můžete ve svém účtu vytvářet ručně na stránce Webhooky. Webhook bude odesílat data, a proto bude zapotřebí, aby byla na druhé straně k dispozici webová služba, která bude data přijímat. Obvykle je na druhé straně skript nebo aplikace, kterou si vytvoříte, může to však být i web třetí strany, ke kterému se webhook připojí.
Úprava zprávy, kterou webhook odesílá
Ve výchozím nastavení webhook posílá všechna dostupná pole ve formátu JSON. Pokud má objekt připojený formulář, bude tento formulář použit také. Můžete určit, aby se neposílala žádná data, nebo aby se posílala data, která definujete. Lze to použít například pro doplnění API klíče nebo autentifikace do zprávy.
Po vytvoření webhooku se automaticky dostanete na obrazovku, kde lze upravit „payload“, neboli zprávu, kterou webhook zasílá. Po kliknutí na „Volitelné“ se objeví JSON editor, kde lze přidávat a mazat jednotlivá pole. Dole na obrazovce jsou vypsána všechna „magická slova“, která budou při generování zprávy nahrazena. Tato magická slova se mění v závislosti na polích, která jsou pro daný objekt povolená.
Vyzkoušení webhooku
Webhooky lze komfortně odlaďovat službou RequestBin. Tato služba vám vygeneruje adresu, kterou můžete použít jako cílovou URL, takže potom můžete přesně sledovat, jaká data se posílají.
Na obrazovce pro úpravu webhooku je také odkaz „Otestovat webhook“ – ten slouží pro manuální spuštění webhooku a úpravu odesílané zprávy. Odchozí volání tak můžete upravit a simulovat například chybu při platbě bez potřeby takovou událost skutečně generovat v rozvrhu.
Testovací zpráva by se měla spustit zhruba po 5 vteřinách po jejím vytvoření. Pokud druhá strana odpoví jiným stavovým kódem než „OK“ (stavový kód mimo rozsah 200 až 300), systém se pokusí odeslat zprávu znovu vždy ve vzrůstajících intervalech. Po 10 nepovedených pokusech je zpráva smazána a pokud má hook více než 5 nedoručených zpráv, bude deaktivován až do manuální aktivace na obrazovce s webhooky. Pokud druhá strana odpoví stavovým kódem „410 Gone“, webhook se ihned vymaže.