Webhooky

1. Co jsou webhooky

Webhooky jsou HTTP POST požadavky, které Mango odesílá na vámi zadanou URL adresu v okamžiku, kdy v systému nastane určitá událost. Místo opakovaného dotazování API (polling) tak váš systém dostane upozornění automaticky a v reálném čase.

Příklad: Když v Mango vznikne nový zákazník, Mango okamžitě odešle POST požadavek na vaši URL s informacemi o události — vy na ni můžete ihned reagovat (zaslat uvítací e-mail, aktualizovat CRM, spustit scénář v Make).

2. Konfigurace webhooků

Webhooky se konfigurují v aplikaci Mango Admin na adrese https://admin.mango.cloud, sekce Webhooky → Konfigurace.

Tato sekce vyžaduje aktivovaný modul Webhooks — pokud ji nevidíte, kontaktujte OG Soft.

2.1 Přidání nové konfigurace

1. Přihlaste se do Mango Admin.
2. V levém menu vyberte Webhooky → Konfigurace.
3. Klikněte na Přidat webhook.
4. Vyplňte formulář (viz tabulka polí níže).
5. Po kliknutí Uložit se zobrazí bezpečnostní klíč (secret) — zkopírujte ho a bezpečně uložte. Zobrazí se pouze jednou.

2.2 Pole konfigurace

Pole	Povinné	Popis
URL	Ano	Adresa, kam Mango odesílá události (musí začínat http:// nebo https://)
Typ objektu	Ano	Jaký typ objektu sledovat (zákazník, zakázka, aktivita…)
Událost	Ne	Konkrétní akce (vytvoření, úprava, smazání); bez výběru = všechny akce daného typu
Rozsah	Ne	Pro které lokace/partnery platí: Vše / konkrétní lokace / konkrétní partner
Formát	Ne	Formát těla požadavku: JSON (výchozí), JSON (text/plain), Form
Synchronní	Ne	Zda Mango čeká na odpověď před dokončením operace (výchozí: Ne)
Aktivní	Ne	Zapnutí/vypnutí webhooku (výchozí: Ano)

2.3 Úprava a smazání

• Úprava: klikněte na ikonu tužky — lze změnit všechna pole kromě bezpečnostního klíče.
• Smazání: klikněte na ikonu koše a potvrďte. Smazání je nevratné.

3. Struktura odesílaného požadavku

3.1 HTTP hlavičky

Každý webhook request obsahuje tyto hlavičky:

POST <vaše URL> HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: 1718647200
X-Mango-Signature: 9c4a3f2e0b1d…

3.2 Tělo požadavku (payload)

{
 “objectType”: “CUSTOMER”,
 “action”: “CREATE”,
 “objectId”: 12345,
 “ct”: 187,
 “cp”: 123
}

Pole	Typ	Popis
objectType	string	Typ objektu, který událost vyvolal
action	string	Typ akce (CREATE, EDIT, DELETE, STATE_CHANGE…)
objectId	integer	ID konkrétního záznamu v Mango
ct	integer	ID lokace (CT), kde událost nastala
cp	integer	ID CIBS partnera

Kompletní seznam dostupných hodnot objectType a action je v dropdownech při konfiguraci webhooku v Mango Admin.

4. Ověření pravosti požadavku (HMAC)

Každý webhook je podepsán pomocí HMAC-SHA256, aby bylo možné ověřit, že pochází skutečně od Mango a nebyl pozměněn.

4.1 Algoritmus ověření

1. Z hlavičky X-Webhook-Timestamp přečtěte časovou značku (Unix timestamp v sekundách).
2. Sestavte podpisový řetězec: {timestamp}.{raw_body} (tečka jako oddělovač, raw_body = celé tělo požadavku beze změn).
3. Vypočtěte HMAC-SHA256 tohoto řetězce pomocí vašeho bezpečnostního klíče (secret z konfigurace).
4. Porovnejte výsledek s hodnotou v hlavičce X-Mango-Signature.

4.2 Příklad v Node.js

const crypto = require(‘crypto’);

function verifyWebhook(timestamp, rawBody, signature, secret) {
   const message = `${timestamp}.${rawBody}`;
   const expected = crypto
       .createHmac(‘sha256’, secret)
       .update(message)
       .digest(‘hex’);
   return crypto.timingSafeEqual(
       Buffer.from(expected),
       Buffer.from(signature)
   );
}

4.3 Příklad v Pythonu

import hmac, hashlib

def verify_webhook(timestamp, raw_body, signature, secret):
   message = f“{timestamp}.{raw_body}“
   expected = hmac.new(
       secret.encode(), message.encode(), hashlib.sha256
   ).hexdigest()
   return hmac.compare_digest(expected, signature)

4.4 Ochrana před replay útoky

Zkontrolujte, že hodnota X-Webhook-Timestamp není příliš stará (doporučujeme toleranci max. 5 minut). Zamezíte tím znovupoužití zachycených požadavků.

5. Synchronní vs asynchronní doručení

Asynchronní (výchozí): Mango odešle webhook po dokončení operace na pozadí. Vaše URL nemusí odpovídat okamžitě a případná nedostupnost neovlivní provoz Mango.

Synchronní: Mango čeká na odpověď vaší URL před dokončením operace. Použijte pouze pokud potřebujete reagovat v reálném čase a je zaručena rychlá dostupnost vaší URL. Timeout jsou 2 sekundy.

⚠️ Synchronní doručení není dostupné pro události ze síťového monitoringu (DEVICE_EVENT.*).

6. Historie volání

V Mango Admin → Webhooky → Historie volání jsou záznamy všech odeslaných webhooků včetně:

• Cílové URL a typu události
• Výsledku (úspěch / chyba / přeskočeno)
• HTTP stavového kódu odpovědi
• Těla požadavku a odpovědi (pro diagnostiku)
• Časových razítek

Pokud vaše integrace neobdržela očekávanou událost, zkontrolujte zde, zda byl webhook odeslán a jaká byla odpověď.

7. Napojení na Make.com

Integrace Mango s Make.com využívá speciální trigger Watch Workflow Hook, který přijímá události z Mango workflow systému (akce CALL_WEBHOOK). Webhook se v tomto případě nekonfiguruje přes Mango Admin — nastavení na straně Mango zajišťuje OG Soft.

Podrobnosti o integraci s Make: Make.com integrace

8. Doporučení pro implementaci

• Vraťte HTTP 200 co nejrychleji — zpracování přijatého webhooků provádějte asynchronně.
• Implementujte idempotenci — za výjimečných okolností může být stejná událost doručena vícekrát.
• Vždy ověřujte HMAC podpis před zpracováním payloadu.
• Logujte přijatá volání pro snadnější diagnostiku.

9. Podpora a zprovoznění

Zprovoznění webhooků (přidělení modulu Webhooks, konfigurace propojení s Make workflow) zajišťuje OG Soft:

• E-mail: [email protected]
• Hotline: +420 468 000 111 (8:00–16:00)