Signierte Webhooks empfangen

Abonnement erstellen

Verwende Integrations oder POST /webhooks/ mit den Zugangsdaten eines Kontoinhabers oder Administrators, für die webhook-Berechtigung vorliegt. Für E-Mail-Ereignisse ist außerdem die Berechtigung read, die Auswahl der Postfächer und eine aktuelle Freigabe für die Postfächer erforderlich. Wähle genau die benötigten Ereignisse und Postfach-IDs aus. Speichere das Signaturgeheimnis, sobald es angezeigt wird.

curl -X POST 'https://cherrymail.net/api/v1/webhooks/' \
  -H "Authorization: Bearer $CHERRYMAIL_API_KEY" \
  -H "Idempotency-Key: example-request-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://your-app.example/cherrymail/events",
  "events": [
    "message.received"
  ],
  "mailbox_ids": [
    123
  ]
}'

Zieladressen müssen öffentliches HTTPS über Port 443 verwenden. Weiterleitungen, private Adressen und interne Netzwerke werden abgelehnt. Der DNS-Eintrag des Ziels wird beim Verbindungsaufbau erneut überprüft.

Verfügbare Ereignisse

E-Mail-Ereignisse enthalten Kennungen und minimale Metadaten. Rufe Nachrichteninhalte und Anhänge über die autorisierte API ab.

Jede Zustellung überprüfen

Lies den rohen Request-Body ein, bevor du das JSON parst. Berechne HMAC-SHA256 über timestamp + "." + rawBody mit deinem Signaturgeheimnis. Vergleiche das Ergebnis mit CherryMail-Signature, einschließlich des Präfixes v1=.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp) ||
      Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false;
  }
  const expected = Buffer.from('v1=' + createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest('hex'));
  const actual = Buffer.from(signature);
  return actual.length === expected.length &&
    timingSafeEqual(actual, expected);
}

Verwende den CherryMail-Timestamp-Header, lehne Zeitstempel außerhalb eines Fünf-Minuten-Fensters ab, vergleiche Signaturen in konstanter Zeit und verhindere Duplikate anhand der stabilen Ereignis-ID.

Zustellung, Wiederholungsversuche & erneute Verarbeitung

Sende umgehend eine 2xx-Antwort und verarbeite das Ereignis anschließend asynchron. Die Zustellung erfolgt mindestens einmal; die Reihenfolge ist nicht garantiert. Es gibt bis zu zehn automatische Versuche mit exponentiellem Backoff.

Sieh dir den Zustellverlauf an, sende Testereignisse und spiele Zustellungen in Integrations manuell erneut ab. Bei einer erneuten Zustellung bleibt die ursprüngliche Ereignis-ID erhalten. Deine Deduplizierung muss daher auch absichtliche Wiederholungen berücksichtigen. Wenn du ein Zugangsmittel oder eine Berechtigung widerrufst, werden davon abhängige Zustellungen gestoppt.