Přejít na obsah

Oznámení5 min čtení

Představujeme Webhooks v2

Webhooks v2 jsou tady – 36 typů událostí, HMAC-SHA256 podpisy, automatické opakování požadavků a kompletní dokumentace pro každý payload.

GAutor

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 webového rozhraní.

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í:

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.

Sdílet

Vyzkoušejte, o čem jste právě četli.

3 000 e-⁠mailů měsíčně zdarma. Bez platební karty.

3 000 e-⁠mailů měsíčně zdarma · Bez platební karty