Webhooky: Prepojenie SuperSaaS s ostatnými webmi
Webhooky sú používateľom definované funkcie (callbacky), pomocou ktorých je možné ostatným aplikáciám a webovým stránkam posielať v reálnom čase informácie o udalostiach, ktoré na vašom účte nastanú.
Príklady použitia webhookov:
- Prihlásenie používateľa do zoznamu adresátov v službe MailChimp pri registrácii v rámci určitého účtu SuperSaaS
- Odoslanie PDF súboru s obchodnými podmienkami e-mailom používateľovi, ktorý sa práve zaregistroval
- Vygenerovanie faktúry v QuickBooks alebo Freshbooks, akonáhle je vytvorená rezervácia
- Akonáhle sa niekto prihlási na určitý vyučovací predmet, bude vykonané označenie v Google Kalendári lektora tejto triedy
- Odoslanie notifikácie na Slack alebo do telefónu chvíľku predtým, než začne schôdzka
- Akonáhle je používateľ presunutý z čakacej listiny na potvrdené miesto, bude mu zaslaná SMS správa
- Presmerovanie odoslaných e-mailov na odoslať e-mail prostredníctvom iného poštového servera
Automatické nastavenie webhookov pomocou služieb Zapier.com alebo Make
Pomocou služieb Zapier.com a Make je možné interaktívne prepájať stovky známych služieb, vrátane SuperSaaS, bez akejkoľvek znalosti programovania. Zapier i Make ponúkajú skúšobné verzie aj bezplatné verzie pre malých používateľov.
Vďaka už hotovým príkladom by malo byť vytváranie webhookov pomerne jednoduché. Informácie o podrobnejšom nastavení a filtrovaní iba niektorých udalostí nájdete nižšie.
Nový používateľ do mailing listu na MailChimpu
Nová rezervácia do Google Kalendára
Nová rezervácia vytvorí faktúru v QuickBooks
Nová rezervácia do e-mailového filtraPodporované triggery
Existuje niekoľko udalostí, ktoré je možné sledovať. Pri niektorých entitách je možné sledovať udalosť „new“ (nový) alebo „change“ (zmena). Udalosť „change“ zahŕňa všetky zmeny, takže sa spustí aj pri udalostiach „new“ a „delete“ (odstránenie). Ak teda nastavíte „Nový používateľ“ i „Zmena používateľa“, spustia sa pri registrácii používateľa oba hooky. Pozor na situáciu, keď nastavíte, že rozvrh nevyžaduje registráciu – v tom prípade sa nikdy nespustí trigger „Nový používateľ“, spustí sa len „Nová rezervácia“.
| Trigger | Spustí sa pri… |
|---|---|
| Nový používateľ | Spustí sa pri registrácii používateľa na vašom účte |
| Zmena používateľa | Spustí sa, keď si používateľ upraví svoje údaje alebo keď za neho údaje upraví administrátor. |
| Nová rezervácia | Spustí sa, keď používateľ alebo administrátor vytvorí rezerváciu v konkrétnom rozvrhu. |
| Zmena rezervácie | Spustí sa pri akejkoľvek zmene rezervácie, vrátane „Nová“, „Odstránenie“, „Umiestnenie z čakacej listiny“, „Platba prijatá“ atď. (Celý zoznam nájdete nižšie) |
| Nový formulár | Spustí sa, keď je vyplnený samostatný formulár. Nespustí sa pri formulároch, ktoré sú pripojené k rezerváciám – v takom prípade sa spustí webhook pre rezerváciu. |
| Zmenený formulár | Spustí sa pri akejkoľvek zmene samostatného formulára (integrovaný formulár spustí triggery „Zmena rezervácie“ alebo „Zmena používateľa“) |
| Odoslať e-mail | Spustí sa pri odosielaní e-mailov z vášho účtu, vrátane e-mailov pre „Zabudnuté heslo“ atď. To je možné využiť pre odoslanie e-mailov z vlastného servera. Pokiaľ je tento webhook aktívny, e-maily sa nebudú odosielať zo serverov SuperSaaS. |
| Pripomienka Follow-up | Spúšťa sa pri pripomienkach a follow-upoch. Pokiaľ je tento webhook aktívny, e-maily s pripomienkami alebo follow-upy sa nebudú odosielať zo serverov SuperSaaS. |
Filtrovanie udalostí
Akonáhle v Zapieri alebo Make prepojíte dve služby, budete mať možnosť udalosti filtrovať. Tu je pár príkladov, ako je možné filtrovanie využiť:
- Posielať SMS iba pri umiestnení z čakacej listiny, nie pri každej zmene rezervácie
- Pri vytvorení rezervácie odoslať pripomienku lektorovi, len pokiaľ ide o jeho predmet, ostatné rezervácie na rovnakom rozvrhu ignorovať
- Odoslať pripomienku vedeniu firmy iba pri rezerváciách presahujúcich 80 EUR
Pri vytváraní webhooku si Zapier/Make vyžiada zo SuperSaaS ukážkový objekt. Ukážkový objekt obsahuje všetky dostupné polia a príklady použitia. To, ktoré polia webhook odošle, závisí na tom, ktoré polia máte na účte povolené a či je pripojený vlastný formulár. Pri väčšine triggerov sú k dispozícii polia „event“ (udalosť) a „role“ (rola), ktoré je možné použiť na filtrovanie. Môžete napríklad filtrovať iba triggery, ktoré majú v poli „event“ hodnotu „delete“.
| Trigger | Možné hodnoty v poli „event“ |
|---|---|
| Nový používateľ | new |
| Zmena používateľa | new, change, delete |
| Nová rezervácia | create |
| Zmena rezervácie | create, edit, place, pending, destroy, restore, approve, revert |
| Nový formulár | new |
| Zmena formulára | new, change, delete, restore |
| Pripomienka / Follow-up | reminder, follow_up |
| Pole „role“ | Kým je udalosť spustená… | |
|---|---|---|
| 0 | Anonymné | Neprihlásený |
| 1 | Prihlásený so zdieľaným heslom | |
| 2 | Používateľ overený pomocou IP rozsahu | |
| 3 | Bežný používateľ | |
| 4 | Superpoužívateľ | |
| 5 | Administrátor alebo reseller | |
| 7 | Systém alebo platobná brána | |
Pri vytváraní alebo zmene rezervácie obsahujúcej platbu nájdete v poliach „status“ (stav) a „status message“ (stavová správa) podrobnosti udalosti – celý zoznam stavov nájdete v sekcii stavové kódy. Môžete tak napríklad vytvoriť filter, ktorým prejdú iba udalosti, ktoré boli refundované.
Ručné nastavenie webhookov (pokročilé)
Táto funkcia je k dispozícii iba pre platiacich zákazníkov. Môžete si ju vyskúšať na týždeň kliknutím na tlačidlo „Začiatok skúšky zadarmo“ na obrazovke s webhookami.
Vytváranie webhookov bez použitia Zapieru alebo Make vyžaduje určité vývojárske zručnosti. Zvyšok tejto stránky obsahuje informácie pre programátorov, ktorí môžu pridať webhook pre odosielanie informácií do ich aplikácie alebo ktorí chcú naprogramovať vlastné rozhranie medzi SuperSaaS a iným webom.
Webhooky môžete vo svojom účte vytvárať ručne na stránke Webhooky. Webhook bude odosielať dáta a preto bude potrebné, aby bola na druhej strane k dispozícii webová služba, ktorá bude dáta prijímať. Zvyčajne je na druhej strane skript alebo aplikácia, ktorú si vytvoríte, môže to však byť aj web tretej strany, ku ktorému sa webhook pripojí.
Úprava správy, ktorú webhook odosiela
V predvolenom nastavení webhook posiela všetky dostupné polia vo formáte JSON. Pokiaľ má objekt pripojený formulár, bude tento formulár tiež použitý. Môžete určiť, aby sa neposielali žiadne dáta, alebo aby sa posielali dáta, ktoré definujete. Je možné to použiť napríklad pre doplnenie API kľúča alebo autentifikáciu do správy.
Po vytvorení webhooku sa automaticky dostanete na obrazovku, kde sa dá upraviť „payload“, čiže správu, ktorú webhook zasiela. Po kliknutí na „Voliteľné“ sa objaví JSON editor, kde je možné pridávať a mazať jednotlivé polia. Dole na obrazovke sú vypísané všetky „magické slová“, ktoré budú pri generovaní správy nahradené. Tieto magické slová sa menia v závislosti na poliach, ktoré sú pre daný objekt povolené.
Vyskúšanie webhooku
Webhooky je možné komfortne odlaďovať službou RequestBin. Táto služba vám vygeneruje adresu, ktorú môžete použiť ako cieľovú URL, takže potom môžete presne sledovať, aké dáta sa posielajú.
Na obrazovke pre úpravu webhooku je tiež odkaz „Otestovať webhook“ – pre manuálne spustenie webhooku a úpravu odosielanej správy. Odchádzajúce volania tak môžete upraviť a simulovať napríklad chybu pri platbe bez potreby takúto udalosť skutočne generovať v rozvrhu.
Testovacia správa by sa mala spustiť zhruba po 5 sekundách po jej vytvorení. Ak druhá strana odpovie iným kódom stavu než „OK“ (kód stavu mimo rozsahu 200 až 300), systém sa pokúsi odoslať správu znova vždy vo narastajúcich intervaloch. Po 10 nevydarených pokusoch je správa zmazaná a ak má hook viac ako 5 nedoručených správ, bude deaktivovaný až do manuálnej aktivácie na obrazovke s webhookami. Ak druhá strana odpovie stavovým kódom „410 Gone“, webhook sa ihneď vymaže.