Na čo je webhook
Webhook je opačný smer ako API: nie vy sa pýtate Monivia, ale Monivio zavolá váš server, keď sa niečo stane - vznikne faktúra, klient zaplatí, pribudne kontakt. Váš systém tak nemusí nič cyklicky kontrolovať. Doručenie býva spravidla do niekoľkých sekúnd od udalosti.
Webhooky sú dostupné od plánu Solo; na pláne Free ich nevytvoríte (viď Zmena tieru predplatného).
Krok 1: Prepnite sa do modulu MonivioIntegration
Webhooky nie sú v bežnom menu s faktúrami. Kliknite vľavo hore na prepínač platformy (nad ľavým menu, predvolene ukazuje MonivioDocuments) a vyberte MonivioIntegration.
Krok 2: Vytvorte webhook
V sekcii Integrácia → Webhooky kliknite na Nový webhook a vyplňte:
- Názov - na rozlíšenie v zozname
- URL - adresa, kam má Monivio posielať POST requesty
- Eventy - ktoré udalosti chcete dostávať (doklady, kontakty, náklady, transakcie); dajú sa vybrať po skupinách alebo všetky naraz
- Custom HTTP headers - voliteľné, napr. autorizačná hlavička vášho systému
- Aktívny - či má webhook prijímať eventy hneď po vytvorení
Krok 3: Uložte si secret
Po vytvorení sa zobrazí secret - rovnako ako API kľúč len jediný raz. Slúži na overenie podpisu prichádzajúcich requestov, aby ste si boli istí, že prišli naozaj z Monivio a nie od niekoho iného.
Ak secret stratíte, v menu webhooku ho viete regenerovať. Starý okamžite prestane platiť, takže nový treba nasadiť do vášho systému hneď.
Krok 4: Skontrolujte, či doručenia prechádzajú
V menu webhooku (ikonka ⋯) je položka Zobraziť logy - presmeruje vás do Integrácia → Analytics, na záložku Webhooky. Nájdete tu graf doručovania a tabuľku pokusov: stav (Úspech, Neúspech, Opakuje sa, Čaká, Odosiela sa), event, webhook, poradie pokusu, trvanie a čas. Zlyhané doručenie sa automaticky opakuje až 5 ×; poradie pokusu vidíte pri každom riadku.
V detaile záznamu vidíte hlavičky aj telo odoslaného requestu a odpovede, HTTP stav a chybu. Zlyhané doručenie sa dá zopakovať tlačidlom Retry manuálne. Či webhook vôbec odpovedá, viete overiť skúšobným volaním cez REST API (POST /api/v1/webhooks/{id}/test); v menu webhooku na to tlačidlo nie je.
Ak váš server opakovane odpovedá chybou, Monivio webhook automaticky deaktivuje a na jeho karte uvidíte stav Deaktivovaný aj dôvod. Po oprave na svojej strane ho v menu Akcie znova zapnite voľbou Reaktivovať.
Monivio nenasleduje presmerovania. Ak adresa webhooku odpovie presmerovaním (stav 3xx), doručenie sa zaráta ako neúspešné a v detaile uvidíte dôvod. Zadajte preto rovno konečnú adresu - teda tú, na ktorú by vás presmerovanie poslalo.
Krok 5: Prehľad na jednom mieste
Položka Dashboard na vrchu menu modulu MonivioIntegration ukazuje počet aktívnych webhookov aj kľúčov a aktivitu za posledné dni. Je to najrýchlejší spôsob, ako zistiť, či integrácia žije.
Čo ďalej?
- API kľúče - autentifikácia pre volania REST API
- Párovanie platieb z banky - časté využitie eventu „faktúra zaplatená“
- Prechod zo SuperFaktúry - jednorazový prenos dát webhook nepotrebuje