Webhooky

Webhooky posílají události z Emailitu do vaší aplikace hned, jak nastanou, takže se nemusíte opakovaně dotazovat API. Použijte je k aktualizaci stavu doručení ve vaší databázi, k zastavení odesílání na adresy, na které se e-maily nedoručují nebo jejichž příjemci si stěžují, k reakci na otevření a prokliky, ke zpracování příchozích e-mailů nebo k synchronizaci kontaktů a blokovaných adres.

Jak to funguje

1. Zaregistrujete endpoint. Ve webovém rozhraní nebo přes API vytvoříte webhook s názvem a HTTPS URL. Emailit pro něj vygeneruje tajný klíč webhooku.
2. Něco se stane. Emailit zaznamená událost, například email.delivered, a zařadí ji do fronty pro každý zapnutý webhook, který odebírá daný typ události a jehož filtr obsahu odpovídá.
3. Emailit odešle dávku. Během několika sekund Emailit odešle požadavek POST, jehož tělem je pole JSON až se 100 událostmi z fronty, od nejstarší. Požadavky na jeden webhook se odesílají jeden po druhém.
4. Váš endpoint odpoví. Jakýkoli stav 2xx do 30 sekund označí všechny události v dávce jako doručené. Cokoli jiného, včetně vypršení časového limitu nebo přesměrování, je selhání a Emailit dávku opakuje asi tři dny.

Každý požadavek má tyto hlavičky:

Úplný formát popisuje stránka Požadavky webhooků, kód pro ověření najdete na stránce Ověření podpisu webhooků.

Rychlý příklad

Tento handler pro Express ověří podpis a pak zpracuje každou událost v dávce:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Emailit-Timestamp') ?? '';
  const signature = req.get('X-Emailit-Signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.EMAILIT_WEBHOOK_SECRET) // whsec_...
    .update(`${timestamp}.`)
    .update(req.body)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!fresh || !valid) return res.status(401).send('Invalid signature');

  for (const event of JSON.parse(req.body)) {
    switch (event.type) {
      case 'email.delivered':
        console.log(`Delivered ${event.data.object.id} to ${event.data.object.to}`);
        break;
      case 'email.bounced':
      case 'email.complained':
        console.log(`Stop sending to ${event.data.object.to}`);
        break;
    }
  }

  res.sendStatus(200);
});

app.listen(3000);

Co můžete odebírat

Webhooky pokrývají doručování e-mailů a zapojení příjemců (email.delivered, email.bounced, email.clicked a další), příchozí poštu (email.received) a změny domén, seznamů kontaktů, odběratelů, kontaktů, šablon, blokovaných adres, ověření e-mailů a kampaní. Nový webhook vytvořený ve webovém rozhraní dostává všechny události; později ho můžete omezit na konkrétní typy. Viz Typy událostí.

V tarifech Pro, Business a Custom může filtr obsahu omezit webhook na události, které odpovídají pravidlům, například jen na e-maily pro jednu doménu.

Limity

Stránka webhooků ukazuje, kolik endpointů využíváte, například 2/3 used. Po dosažení limitu je tlačítko Add webhook neaktivní, dokud některý webhook nesmažete nebo nepřejdete na vyšší tarif. Každý webhook může odeslat nejvýše 5 testovacích událostí za minutu.

Začínáme