Webhooky
real-time notifikace

Jak webhooky fungují?

Webhook je HTTP POST požadavek, který TopSMS odešle na vaši URL v okamžiku, kdy se změní stav SMS zprávy. Váš server přijme JSON payload s informacemi o zprávě a potvrdí přijetí HTTP kódem 200.

Webhooky jsou push model — oproti polling modelu (pravidelné dotazování GET endpointu) šetří zdroje vašeho serveru a eliminují zpoždění způsobené intervalem dotazování.

• Notifikace při stavu: DELIVERED, UNDELIVERED, EXPIRED, REJECTED
• Notifikace při opt-out odhlášení příjemce
• JSON payload s ID zprávy, stavem, časovými razítky
• Notifikace přichází do 2 sekund od změny stavu
• Konfigurace URL v dashboardu nebo přes API

Retry logika a spolehlivost

Pokud váš server odpoví jiným kódem než 2xx (nebo vůbec neodpoví), TopSMS automaticky zopakuje odeslání notifikace. Retry probíhá 3× s exponenciálním backoffem — po 30 sekundách, 5 minutách a 30 minutách.

Po 3 neúspěšných pokusech je webhook označen jako nedoručený a událost je zaznamenána v audit logu. Zmeškané notifikace lze zpětně dohledat přes REST API polling endpoint.

• Automatický retry 3× při neúspěšném doručení
• Exponenciální backoff: 30s → 5min → 30min
• Audit log všech webhook notifikací
• Fallback: REST API polling jako záloha

Bezpečnost — HMAC podpis

Každý webhook požadavek je podepsán HMAC-SHA256 podpisem vypočítaným z těla požadavku a vašeho tajného klíče. Ověřením podpisu zajistíte, že notifikace skutečně pochází z TopSMS a nebyla upravena.

• Hlavička: X-TopSMS-Signature: sha256=...
• Výpočet: HMAC-SHA256(body, webhook_secret)
• Tajný klíč nastavíte v dashboardu nebo přes API
• Ukázkový kód ověření pro PHP, Python a Node.js v dokumentaci