Spracovanie webhooku vo vašom systéme

Tento návod je pre toho, kto pripravuje druhú stranu prepojenia: adresu, na ktorú Gram CRM webhook posiela, a jeho spracovanie. Opisuje, čo presne príde, ako odpovedať a ako si načítať údaje záznamu.

Požiadavka

Gram pošle na adresu z nastavenia webhooku vždy požiadavku POST s hlavičkou Content-Type: application/json; charset=UTF-8. Podľa nastavenej autorizácie pridá jednu z hlavičiek:

Autorizácia v Grame	Hlavička požiadavky
Žiadna	žiadna
Basic (užívateľ + heslo)	`Authorization: Basic …` (HTTP Basic)
Bearer token	`Authorization: Bearer {token}`
Vlastná hlavička	`{názov hlavičky}: {hodnota}`, napríklad `X-Token: …`

Webhook prijímajte iba cez HTTPS a pri každej požiadavke overte nastavenú autorizáciu. Požiadavku bez správnej hlavičky odmietnite.

Správa pri spúšťači Udalosti záznamu

Správa hovorí, ktorý záznam sa zmenil a ako. Údaje samotného záznamu neobsahuje.

{
  "Data": {
    "Entity": "Account",
    "Id": "069719ba-aeca-47fc-bd92-0ff774bbc028",
    "Event": "create"
  }
}

Pole	Význam
`Entity`	názov entity v API, napríklad `Account` pre klientov alebo `Product` pre produkty. Zoznam entít je v dokumentácii API.
`Id`	Id záznamu
`Event`	`create` (vytvorenie), `edit` (úprava) alebo `delete` (zmazanie)

Načítanie údajov záznamu cez API

Aktuálne údaje záznamu si načítate cez API Gram CRM podľa Entity a Id zo správy. Na prihlásenie použite API kľúč, ktorý správca vytvorí v časti Nastavenia, Integrácie, API kľúče (návod). Kľúč má oprávnenia používateľa, ktorému patrí, preto pre prepojenie odporúčame samostatného používateľa, ktorý vidí len to, čo druhý systém potrebuje.

curl https://api.gramcrm.com/vasafirma/api/v1/Account/069719ba-aeca-47fc-bd92-0ff774bbc028 \
  -H "Authorization: Bearer VAS_API_KLUC"

Namiesto vasafirma doplňte názov vašej organizácie, rovnaký ako v adrese aplikácie. Pri udalosti delete už záznam nenačítate, stačí ho podľa Id odstrániť alebo označiť vo vašom systéme.

Správa pri spúšťači Automatizácia

Správa obsahuje parametre, ktoré používateľ nastavil v kroku Odoslať webhook, pod názvami, ktoré im dal. Všetky hodnoty prídu ako text.

{
  "Data": {
    "orderId": "b48399a2-f8b9-4216-9543-b8c1f5b7197a",
    "amount": "150.00"
  }
}

Ak potrebujete ďalšie údaje, požiadajte o doplnenie parametra v kroku, alebo si záznam načítajte cez API rovnako ako pri udalostiach záznamu. Na to musí krok posielať aj Id záznamu.

Odpoveď

Úspešné doručenie potvrdíte odpoveďou s kódom 2xx, napríklad 200 alebo 204. Obsah odpovede Gram ďalej nespracúva. Na pripojenie čaká Gram 5 sekúnd a na celú odpoveď 10 sekúnd. Iný kód, chyba spojenia alebo prekročený čas sa považujú za neúspech a Gram požiadavku zopakuje.

Keď je nastavená autorizácia, Gram presmerovanie nenasleduje, aby prihlasovacie údaje neodišli na inú adresu. Odpoveď 301 alebo 302 je vtedy neúspech, preto do nastavenia webhooku zadajte presnú konečnú adresu.

Webhook potvrďte čo najskôr kódom 2xx. Ak spracovanie trvá dlhšie, správu si uložte do vlastného frontu a spracujte ju až po odoslaní odpovede.

Poradie a opakované správy

Správy jedného webhooku prichádzajú v poradí, v akom vznikli. Kým sa nepodarí doručiť staršiu, novšie čakajú.
Ako dlho a ako často sa Gram pokúša o doručenie, je v návode Výpadky a doručovanie webhooku.

Pripravte spracovanie na opakovanú správu

Ak váš systém správu spracuje, ale neodpovie včas, Gram ju pošle znova. Spracovanie má byť idempotentné, teda opakované prijatie rovnakej správy nesmie vytvoriť duplicitný výsledok. Pri udalostiach záznamu napríklad záznam podľa Id aktualizujte, nezakladajte nový.

Mohlo by vás tiež zaujímať: