Referenz

Webhooks

Empfangen Sie Events in Echtzeit, damit Ihr System stets weiß, was aus jeder Nachricht wurde. Prüfen Sie jede Anfrage anhand ihrer Signatur.

So funktionieren Webhooks

Registrieren Sie im Dashboard einen HTTPS-Endpunkt und wählen Sie die gewünschten Events. Passiert etwas mit einer Nachricht, sendet MigoSMTP einen POST-Request mit JSON-Body an Ihren Endpunkt.

Event-Typen

Abonnieren Sie nur die Events, die Ihr System braucht. Jedes Event enthält die Message-ID, den Empfänger und einen Zeitstempel, damit Sie es der gesendeten Nachricht zuordnen können.

Beispiel-Payload

Payloads sind JSON und werden per POST-Request gesendet. Die Werte hier sind nur Beispiele.

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

Signatur verifizieren

Jeder, der Ihre URL kennt, könnte dorthin posten. Prüfen Sie daher jede Anfrage. Berechnen Sie einen HMAC über den rohen Request-Body mit Ihrem Signing Secret und vergleichen Sie ihn per Constant-Time-Vergleich mit dem Wert im Signatur-Header. Weisen Sie nicht passende Anfragen ab. Header-Name und Algorithmus stehen bei Ihrem Signing Secret im Dashboard.

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Schnell antworten

Geben Sie einen 2xx-Status zurück, sobald Sie das Event gespeichert haben, und erledigen Sie die eigentliche Arbeit danach in einer Queue. Ein langsamer oder fehlerhafter Endpunkt löst Wiederholungen aus und kann Ihre anderen Events verzögern.

Mit Duplikaten und falscher Reihenfolge rechnen

Fehlgeschlagene Zustellungen werden wiederholt, daher kann dasselbe Event mehrfach eintreffen, und Events können in anderer Reihenfolge ankommen. Machen Sie Ihren Handler mit Message-ID und Event-Typ idempotent und verwenden Sie den Zeitstempel des Events statt der Ankunftszeit.

Testen, bevor Sie sich darauf verlassen

Richten Sie den Endpunkt auf einen Request-Inspector oder einen Tunnel zu Ihrem Entwicklungsrechner, senden Sie eine Testnachricht und prüfen Sie, ob Sie die Signatur im echten Traffic verifizieren können.

EventBedeutung

deliveredDer empfangende Server hat die Nachricht angenommen.

bouncedDie Nachricht konnte nicht zugestellt werden. Senden Sie nicht weiter an diese Adresse, es sei denn, es war ein vorübergehendes Problem.

deferredEin vorübergehender Fehler; die Zustellung wird erneut versucht.

openedDer Empfänger hat die Nachricht geöffnet. Werten Sie das als ungefähres Signal, da Mail-Apps Bilder vorab laden können.

clickedDer Empfänger hat auf einen getrackten Link geklickt.

complainedDer Empfänger hat die Nachricht als Spam gemeldet. Senden Sie nicht weiter an diese Adresse.

War diese Seite hilfreich?Support kontaktieren