Webhooks
Webhooks pushen Ereignisse in dem Moment an Ihr Backend, in dem sie passieren — eine Nachricht wurde zugestellt, ein Link wurde geklickt, ein Kontakt hat sich abgemeldet. Jeder Payload ist signiert, sodass Sie ihm vertrauen können, und fehlgeschlagene Zustellungen werden mit Backoff erneut versucht, sodass ein kurzer Ausfall nie ein Ereignis verliert.
Was Sie brauchen
- Ein öffentlicher HTTPS-Endpunkt zum Empfang von POSTs
- Ein API-Key oder Admin-Zugang zum Registrieren des Webhooks
Einen Endpunkt registrieren
- 1
Einstellungen → Webhooks öffnen
Oder rufen Sie POST /v1/workspaces/{workspace_id}/webhooks auf. Geben Sie Ihre HTTPS-URL an und wählen Sie die gewünschten Ereignisse.
- 2
Signatur-Secret speichern
Jeder Webhook hat ein Secret, das bei der Erstellung angezeigt wird. Damit verifizieren Sie jede eingehende Anfrage.
- 3
Eigene Header hinzufügen (optional)
Hängen Sie Header an (z. B. ein Auth-Token), die Climails bei jeder Zustellung an Ihren Endpunkt sendet.
Ereignisse, die Sie abonnieren können
- E-Mail — email.delivered, email.bounce, email.complaint, email.unsubscribe, email.opened, email.clicked.
- SMS — sms.delivered, sms.failed.
- Kontakte — contact.subscribed, contact.unsubscribed, contact.changed.
- Kampagnen — campaign.finished.
Die Signatur verifizieren
Jede Anfrage trägt X-Senderbox-Timestamp und X-Senderbox-Sig. Berechnen Sie das HMAC neu und vergleichen Sie — weisen Sie alles zurück, was nicht passt, und weisen Sie alte Zeitstempel zurück, um Replays zu stoppen.
// signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-senderbox-timestamp"];
const sig = headers["x-senderbox-sig"]; // "sha256=<hex>"
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(ts + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}Retries und Fehler
Geben Sie schnell ein 2xx zurück, um zu bestätigen. Wenn Ihr Endpunkt einen Fehler liefert oder ein Timeout hat, versucht Climails es mit wachsendem Backoff erneut: 30s, 2m, 10m, 1h, 6h, 24h.
- Nach 6 fehlgeschlagenen Versuchen wird die Zustellung verworfen.
- Ein 4xx (außer 408 und 429) gilt als endgültig und wird nicht erneut versucht — beheben Sie den Endpunkt, dann läuft es beim nächsten Ereignis weiter.
- Endpunkte sind SSRF-geschützt: interne/private Adressen werden abgelehnt.
Häufig gestellte Fragen
Wie verifiziere ich, dass ein Webhook wirklich von Climails stammt?
Berechnen Sie HMAC-SHA256 über timestamp + "." + rohen Body mit dem Secret des Webhooks neu und vergleichen Sie mit X-Senderbox-Sig. Nutzen Sie einen konstantzeitigen Vergleich.
Was passiert, wenn mein Server ausfällt?
Zustellungen werden mit Backoff (30s → 24h) über bis zu 6 Versuche erneut versucht, sodass ein kurzer Ausfall keine Ereignisse verliert.
Warum hat mein Webhook sofort aufgehört, Retries zu machen?
Eine 4xx-Antwort (außer 408/429) gilt als permanenter Fehler. Beheben Sie den Handler; neue Ereignisse werden wieder zugestellt.
In Minuten mit dem Versand starten
Kostenloses Konto erstellen, Domain verbinden und Ihre Zielgruppe über alle Kanäle erreichen – ohne Kreditkarte.
Dauerhaft kostenloser Tarif · Keine Kreditkarte · In Minuten startklar