Webhooks

Webhooks übertragen Events von Emailit an Ihre Anwendung, sobald sie eintreten, sodass Sie die API nicht regelmäßig abfragen müssen. Nutzen Sie sie, um den Zustellstatus in Ihrer Datenbank zu aktualisieren, keine E-Mails mehr an Adressen zu senden, die bouncen oder sich beschweren, auf Öffnungen und Klicks zu reagieren, eingehende E-Mails zu verarbeiten oder Kontakte und Sperrungen zu synchronisieren.

So funktioniert es

1. Sie registrieren einen Endpunkt. Erstellen Sie in der Weboberfläche oder per API einen Webhook mit einem Namen und einer HTTPS-URL. Emailit generiert dafür ein Signatur-Secret.
2. Etwas passiert. Emailit zeichnet ein Event auf, zum Beispiel email.delivered, und stellt es für jeden aktivierten Webhook in die Warteschlange, der diesen Event-Typ abonniert hat und dessen Payload-Filter zutrifft.
3. Emailit sendet einen Batch. Innerhalb von Sekunden sendet Emailit eine POST-Anfrage, deren Body ein JSON-Array mit bis zu 100 wartenden Events ist, die ältesten zuerst. Anfragen an einen Webhook werden nacheinander gesendet.
4. Ihr Endpunkt antwortet. Jeder 2xx-Status innerhalb von 30 Sekunden markiert alle Events im Batch als zugestellt. Alles andere, auch ein Timeout oder ein Redirect, gilt als Fehlschlag, und die Zustellung des Batches wird etwa drei Tage lang wiederholt.

Jede Anfrage enthält diese Header:

Das vollständige Format finden Sie unter Webhook-Anfragen, Code zur Verifizierung unter Anfragesignatur.

Kurzes Beispiel

Dieser Express-Handler verifiziert die Signatur und verarbeitet dann jedes Event im Batch:

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);

Was Sie abonnieren können

Webhooks decken Zustellung und Engagement von E-Mails ab (email.delivered, email.bounced, email.clicked und mehr), eingehende E-Mails (email.received) sowie Änderungen an Domains, Kontaktlisten, Abonnenten, Kontakten, Vorlagen, Sperrungen, E-Mail-Verifizierungen und Kampagnen. Ein neuer Webhook, der in der Weboberfläche erstellt wird, erhält alle Events; Sie können ihn später auf bestimmte Typen einschränken. Siehe Event-Typen.

In den Tarifen Pro, Business und Custom kann ein Payload-Filter einen Webhook auf Events beschränken, die bestimmten Regeln entsprechen, zum Beispiel nur E-Mails an eine Domain.

Limits

Die Webhook-Seite zeigt, wie viele Endpunkte Sie nutzen, zum Beispiel 2/3 used. Wenn Sie das Limit erreichen, ist Add webhook deaktiviert, bis Sie einen löschen oder in einen höheren Tarif wechseln. Jeder Webhook kann höchstens 5 Test-Events pro Minute senden.

Erste Schritte