Slovník pojmů

Webhook

Také: callback, HTTP notifikace

Webhook je HTTP požadavek (obvykle POST s JSON tělem), který služba pošle na URL vaší aplikace, jakmile nastane událost, například změna stavu doručení e-mailu.

Místo opakovaného dotazování (polling) na stav každého e-mailu dostane aplikace zprávu sama: e-mail doručen, odložen, odmítnut, stížnost. Z toho může zobrazit stav v administraci, poslat SMS jako zálohu, nebo požádat zákazníka o opravu adresy.

Správný příjem webhooku: ověřit podpis (HMAC) z nezparsovaného těla, uložit událost a odpovědět 200 do pár sekund, zpracování nechat na pozadí a počítat s tím, že stejná událost může přijít víckrát. Při neúspěšné odpovědi služba doručení opakuje s rostoucím odstupem.

POST https://firma.cz/webhooks/topemail
X-TopEmail-Signature: sha256=3f1c…

{ "event": "email.status", "id": "evt_7f3a1", "emailId": "em_…", "status": "delivered", "to": "zakaznik@seznam.cz", "tags": {"order":"10234"} }

// jak to souvisí s TopEmail

TopEmail posílá webhook email.status při každé změně stavu, podepsaný HMAC v hlavičce X-TopEmail-Signature; testovací odeslání spustíte z dashboardu.

// související pojmy

HMAC podpis Idempotence (Idempotency-Key)Bounce (hard a soft)API klíč