Představujeme Webhooks v2

Spouštíme Webhooks v2 – kompletní přepracování způsobu, jakým Emailit doručuje oznámení o událostech v reálném čase do vašich aplikací. S 36 typy událostí napříč 9 kategoriemi zdrojů, kryptografickým ověřováním podpisů a robustní strategií opakování vám Webhooks v2 poskytuje vše potřebné pro vytváření spolehlivých integrací řízených událostmi.

Co je nového

36 typů událostí napříč 9 zdroji

Webhooks v2 pokrývají každý zdroj v Emailit. Můžete se přihlásit k odběru přesně těch událostí, které vás zajímají, nebo použít all_events pro příjem všech.

Události e-mailů sledují celý životní cyklus doručení:

Událost	Popis
email.accepted	Přijato k doručení
email.scheduled	Naplánováno k budoucímu doručení
email.delivered	Doručeno na mailový server příjemce
email.bounced	Trvale neúspěšné (tvrdý odraz)
email.attempted	Dočasné selhání doručení
email.failed	Selhalo kvůli konkrétní chybě
email.rejected	Přijato a poté odmítnuto
email.suppressed	Příjemce je na seznamu potlačených
email.received	Příchozí e-mail byl přijat
email.complained	Zaregistrována stížnost na spam
email.clicked	Byl kliknut odkaz v e-mailu
email.loaded	Obsah e-mailu byl načten (otevřen)

CRUD události pro domény, publikum, odběratele, kontakty, šablony, potlačení, ověření e-mailů a seznamy ověření e-mailů, každý s událostmi .created, .updated a .deleted.

Konzistentní struktura událostí

Každý webhook payload následuje stejnou strukturu, což usnadňuje vytvoření jediného handleru pro všechny události:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

event_id jednoznačně identifikuje každou událost, type vám říká, co se stalo, a data.object obsahuje kompletní zdroj v době události.

Ověření podpisu HMAC-SHA256

Každý webhook požadavek je podepsán vaším webhook tajemstvím pomocí HMAC-SHA256. Podpis se počítá nad {timestamp}.{rawBody}, takže můžete ověřit autenticitu i čerstvost v jednom kroku.

Každý požadavek obsahuje dva hlavičky:

• X-Emailit-Signature — HMAC-SHA256 hex digest
• X-Emailit-Timestamp — Unix timestamp použitý v podpisu

Důrazně doporučujeme používat timing-safe porovnání (např. crypto.timingSafeEqual v Node.js) pro prevenci timing útoků a odmítat požadavky s timestampy staršími než několik minut jako ochranu proti replay útokům.

Kompletní příklady ověření v Node.js, Python, PHP, Ruby a Go jsou dostupné v dokumentaci Podpis požadavku.

Automatické opakování s exponenciálním backoffem

Pokud váš endpoint neodpoví s 2xx do 30 sekund, Emailit automaticky opakuje:

Pokus	Zpoždění
0	5 sekund
1	5 minut
2	30 minut
3	2 hodiny
4	5 hodin
5	10 hodin
6	24 hodin

To je celkem 7 pokusů během přibližně 41 hodin. Po posledním pokusu je webhook automaticky deaktivován. Můžete ho kdykoli znovu aktivovat z dashboardu.

Formát požadavku

Všechny webhook požadavky jsou POST s JSON tělem. Každý požadavek obsahuje tyto hlavičky:

Hlavička	Popis
Content-Type	application/json
User-Agent	Emailit-Webhook/1.0
X-Emailit-Signature	HMAC-SHA256 podpis
X-Emailit-Timestamp	Unix timestamp použitý v podpisu

Osvědčené postupy

• Odpovídejte rychle — Vraťte 2xx okamžitě a zpracujte payload asynchronně v background jobu.
• Zvládejte duplikáty — Stejná událost může být během opakování doručena vícekrát. Použijte event_id pro deduplikaci.
• Ověřujte podpisy — Vždy validujte hlavičku X-Emailit-Signature pro potvrzení, že požadavek přišel z Emailit.
• Chraňte se před replay útoky — Zkontrolujte X-Emailit-Timestamp a odmítněte požadavky starší než několik minut.

Kompletní dokumentace

Publikovali jsme kompletní dokumentaci pro Webhooks v2 s detailními příklady payloadů a popisy polí pro všech 36 událostí:

• Úvod — Přehled a jak webhooky fungují
• Typy událostí — Kompletní seznam všech 36 typů událostí
• Webhook požadavky — Formát požadavku, hlavičky a strategie opakování
• Podpis požadavku — Ověření podpisu s příklady kódu v 5 jazycích

Začněte

Přejděte do dokumentace Webhooks a začněte, nebo skočte přímo do API Reference pro vytvoření vašeho prvního webhook endpointu.