Webhooks konfigurieren

Published: 16. Juli 2026 · Last updated: 21. Juli 2026 · By Marcus Biel

Webhooks ermöglichen es Maildroppa, eine andere Anwendung zu benachrichtigen, wenn in Ihrem Konto etwas Wichtiges geschieht.

Anstatt Maildroppa wiederholt zu fragen, ob ein Abonnent erstellt, aktualisiert, abgemeldet oder mit einem Tag versehen wurde, kann Ihre Anwendung kurz nach dem Ereignis eine HTTPS-Anfrage empfangen.

Die Webhooks-Seite ist der zentrale Ort für diese kontoweite Integration. Sie können mehrere Endpunkte erstellen, die von jedem Endpunkt empfangenen Ereignisse auswählen, Authentifizierungs-Header hinzufügen, die Verbindung testen, Zustellversuche prüfen und bei Bedarf ein Ereignis aus der Produktion erneut abspielen.

Funktionsweise von Konto-Webhooks

Ein Konto-Webhook funktioniert wie folgt:

1. In Maildroppa tritt ein Ereignis ein, z. B. die Erstellung eines Abonnenten.
2. Maildroppa ermittelt jeden aktiven Endpunkt, der dieses Ereignis abonniert hat.
3. Maildroppa erstellt für jeden passenden Endpunkt eine Zustellung.
4. Die JSON-Nutzlast wird mit dem Webhook-Signaturgeheimnis Ihres Kontos signiert.
5. Maildroppa sendet eine HTTPS-POST-Anfrage an die gespeicherte Endpunkt-URL.
6. Ihr Endpunkt überprüft die Signatur, speichert oder verarbeitet das Ereignis und gibt eine HTTP-Antwort zurück.
7. Maildroppa protokolliert das Ergebnis im Zustellverlauf und wiederholt vorübergehende Fehler automatisch.

Wenn mehrere Endpunkte dasselbe Ereignis abonnieren, erhält jeder Endpunkt eine eigene Zustellung. Das Geschäftsevent hat für alle dieselbe Ereignis-ID, während jede Zustellung ihre eigene Zustell-ID besitzt.

Konto-Webhooks unterscheiden sich von einem Schritt „Webhook senden“ innerhalb einer Automation. Konto-Webhooks hören kontoweit in Maildroppa auf ausgewählte Ereignisse. Ein Automation-Webhook wird nur gesendet, wenn ein Abonnent genau diesen Schritt erreicht. Beide verwenden das Webhook-Signaturgeheimnis des Kontos. Eine Rotation des Geheimnisses wirkt sich daher auf jeden ausgehenden Webhook-Empfänger aus, der Maildroppa-Signaturen überprüft.

Webhooks-Seite öffnen

Öffnen Sie „Einstellungen“, erweitern Sie „Entwickler“ und wählen Sie „Webhooks“ aus.

Die Seite enthält drei Hauptbereiche:

• Signaturgeheimnis
• Endpunkte
• Zustellverlauf für den ausgewählten Endpunkt

Wenn Sie mehr als einen Endpunkt haben, wählen Sie eine Endpunktzeile aus, um deren Zustellverlauf anzuzeigen. Wenn Sie keinen Endpunkt ausdrücklich ausgewählt haben, zeigt Maildroppa den Verlauf des ersten Endpunkts in der Liste an.

Vor dem Erstellen eines Endpunkts

Richten Sie einen Empfänger auf Ihrem Server ein, bevor Sie Maildroppa konfigurieren. Der Empfänger sollte:

• über eine öffentliche HTTPS-URL erreichbar sein.
• POST-Anfragen mit einem application/json-Body akzeptieren.
• den unveränderten Request-Body aufbewahren, bis die Maildroppa-Signatur überprüft wurde.
• erst dann einen 2xx-Status zurückgeben, wenn das Ereignis sicher angenommen wurde.
• wiederholte Zustellungen anhand der Ereignis-ID idempotent verarbeiten.
• schnell antworten, statt während der Anfrage langsame Arbeiten auszuführen.

Ein zuverlässiges Muster besteht darin, die Anfrage zu überprüfen, die Ereignis-ID und die Nutzlast in einer dauerhaften Warteschlange oder Datenbank zu speichern, 200 oder 204 zurückzugeben und die Geschäftsaktion anschließend zu verarbeiten.

Machen Sie keinen Entwicklungscomputer, keine lokale Netzwerkadresse und kein ungeschütztes Skript zu einem Produktions-Webhook-Empfänger. Maildroppa akzeptiert nur öffentliche HTTPS-Ziele und überprüft das Ziel erneut, wenn eine Zustellung gesendet wird.

Schritt 1: Signaturgeheimnis generieren

Jede Maildroppa-Webhook-Anfrage wird signiert. Ihr Empfänger verwendet das Signaturgeheimnis, um zu überprüfen, dass die Anfrage von Maildroppa erstellt wurde und der Body während der Übertragung nicht verändert wurde.

Oben auf der Seite zeigt das Bedienfeld „Signaturgeheimnis“ einen dieser Zustände:

• Fehlt — Es ist noch kein Signaturgeheimnis vorhanden.
• Bereit — Ein Signaturgeheimnis ist konfiguriert.
• Wird geladen — Maildroppa ruft den aktuellen Status ab.

Klicken Sie auf „Geheimnis generieren“, wenn der Status „Fehlt“ lautet.

Maildroppa zeigt das neue Geheimnis sofort an. Es beginnt mit whsec_. Klicken Sie auf „Kopieren“ und speichern Sie es im Secret-Manager oder in der geschützten Umgebungskonfiguration, die Ihr Empfänger verwendet.

Der vollständige Wert wird nur unmittelbar nach der Generierung oder Rotation angezeigt. Wenn Sie die Seite neu laden oder verlassen, zeigt Maildroppa nur an, dass ein Geheimnis vorhanden ist und wann es zuletzt aktualisiert wurde. Das gespeicherte Geheimnis wird nicht erneut angezeigt.

Wenn Sie das Geheimnis verlieren

Wenn der Empfänger das aktuelle Geheimnis nicht mehr besitzt, klicken Sie auf „Geheimnis rotieren“ und speichern Sie den neu angezeigten Wert.

Durch die Rotation wird das vorherige Geheimnis sofort ersetzt. Maildroppa bewahrt nicht beide Werte für eine Übergangszeit auf. Aktualisieren Sie jeden Empfänger, der dieses Kontogeheimnis verwendet, bevor Sie weitere Tests senden oder sich auf Produktionszustellungen verlassen.

Neue Zustellungen, geplante Wiederholungen, Tests und erneute Wiedergaben werden zum Zeitpunkt der HTTP-Anfrage mit dem aktuellen Geheimnis signiert. Das bedeutet, dass eine vor der Rotation erstellte Zustellung bei einem späteren Versuch trotzdem mit dem neuen Geheimnis signiert werden kann.

Behandeln Sie das Geheimnis wie ein Passwort

Platzieren Sie das Signaturgeheimnis nicht in Browser-Code, einem öffentlichen Repository, einer URL, einer Fehlerseite oder einem gewöhnlichen Anwendungslog.

Nur der serverseitige Empfänger benötigt das Geheimnis. Wenn Sie vermuten, dass es offengelegt wurde, rotieren Sie es und aktualisieren Sie umgehend alle Empfänger.

Signatur eines Webhooks überprüfen

Jede Anfrage enthält diese Maildroppa-Header:

• X-Maildroppa-Event-Id — Identifiziert das Geschäftsevent.
• X-Maildroppa-Delivery-Id — Identifiziert diese bestimmte Zustellung.
• X-Maildroppa-Timestamp — Der Signaturzeitpunkt als Unix-Sekunden.
• X-Maildroppa-Signature — Die versionierte HMAC-Signatur.

Maildroppa sendet außerdem:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

Die Signatur hat dieses Format:

v1=<lowercase hexadecimal HMAC>

Maildroppa erstellt sie mit HMAC-SHA256. Der signierte Inhalt besteht aus dem Zeitstempel, gefolgt von einem Punkt und dem exakt unveränderten JSON-Request-Body:

<timestamp>.<raw request body>

Verwenden Sie das Signaturgeheimnis als HMAC-Schlüssel.

Das folgende Node.js-Beispiel zeigt den wesentlichen Prüfschritt. rawBody muss die ursprünglichen Request-Bytes enthalten, nicht JSON, das bereits geparst und erneut serialisiert wurde.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Vergleichen Sie nach der Signaturprüfung außerdem den Zeitstempel mit Ihrer Serverzeit. Lehnen Sie Anfragen außerhalb einer kurzen, für Ihre Infrastruktur gewählten Toleranz ab, beispielsweise fünf Minuten. Dadurch wird das Risiko verringert, dass eine aufgezeichnete gültige Anfrage wesentlich später erneut abgespielt wird.

Parsen und verarbeiten Sie das JSON erst, nachdem beide Prüfungen erfolgreich waren.

Häufige Ursachen für Signaturfehler

Eine Signatur schlägt normalerweise aus einem dieser Gründe fehl:

• Der Empfänger verwendet nach einer Rotation ein altes Geheimnis.
• Middleware hat das JSON geparst oder verändert, bevor die Signatur berechnet wurde.
• Der Empfänger signiert nur den Body und lässt <timestamp>. weg.
• Der Zeitstempel wird als formatiertes Datum statt als exakter Header-Wert behandelt.
• Das Präfix v1= wird beim Vergleich weggelassen.
• Der berechnete HMAC wird anders als in Kleinbuchstaben im Hexadezimalformat codiert.

Protokollieren Sie bei einer fehlgeschlagenen Überprüfung die Ereignis-ID und die Zustell-ID, aber niemals das Signaturgeheimnis oder vertrauliche Werte benutzerdefinierter Header.

Schritt 2: Einen Endpunkt hinzufügen

Klicken Sie im Bereich „Endpunkte“ auf „Endpunkt hinzufügen“.

Der Editor enthält vier Teile:

• Endpunkt-URL
• Ereignisse
• Benutzerdefinierte Header
• Aktivstatus

Neue Endpunkte werden als aktiv angelegt, und zunächst sind alle im Editor angezeigten Ereignisse ausgewählt. Überprüfen Sie die Auswahl vor dem Speichern, damit der Empfänger nur die tatsächlich benötigten Benachrichtigungen erhält.

Endpunkt-URL konfigurieren

Geben Sie die vollständige öffentliche URL ein, die Maildroppa-Anfragen empfangen soll, zum Beispiel:

https://integrations.example.com/webhooks/maildroppa

Die URL muss diese Anforderungen erfüllen:

• Sie muss https:// verwenden.
• Sie muss einen gültigen öffentlichen Hostnamen enthalten.
• Sie darf bis zu 2.048 Zeichen lang sein.
• Sie darf keine Vorlagenvariablen mit { oder } enthalten.
• Sie darf keinen Benutzernamen oder kein Passwort vor dem Hostnamen enthalten.
• Sie darf kein URL-Fragment enthalten, das mit # beginnt.
• Sie muss den standardmäßigen HTTPS-Port 443 verwenden.
• Sie darf nicht localhost, eine rohe IP-Adresse oder einen Hostnamen verwenden, der in ein blockiertes privates oder reserviertes Netzwerk aufgelöst wird.

Abfrageparameter werden unterstützt. Platzieren Sie jedoch keine API-Schlüssel oder anderen Geheimnisse in der URL. URLs sind in der Endpunktliste und in den Zustelldaten sichtbar. Verwenden Sie stattdessen einen benutzerdefinierten Header für Zugangsdaten.

Maildroppa folgt keinen Weiterleitungen. Speichern Sie das endgültige HTTPS-Ziel statt einer URL, die 301, 302, 307 oder 308 zurückgibt.

Der Hostname des Ziels wird vor dem Senden erneut aufgelöst. Ein Hostname, der später in eine private oder blockierte Adresse aufgelöst wird, wird abgelehnt, selbst wenn er beim Speichern des Endpunkts gültig war.

Ereignisse auswählen

Wählen Sie mindestens ein Ereignis aus. Ein Endpunkt empfängt nur die in seinem Editor ausgewählten Ereignistypen.

Die Seite bietet diese Ereignisauswahlen:

Abonnent erstellt — subscriber.created

Wird gesendet, wenn ein Abonnent im Maildroppa-Konto erstellt wird.

Verwenden Sie dieses Ereignis, um den entsprechenden Kontakt in einem CRM, einer Kundendatenplattform, einer internen Datenbank oder einem anderen System mit Berechtigungsverwaltung zu erstellen.

Interpretieren Sie dieses Ereignis nicht als Beweis dafür, dass jede Anmeldung das Double-Opt-in abgeschlossen hat. Der Abonnentenstatus in der Nutzlast beschreibt den aktuellen Zustand.

Abonnent aktualisiert — subscriber.updated

Wird gesendet, wenn sich integrierte Abonnenteninformationen oder Werte benutzerdefinierter Felder ändern.

Verwenden Sie das vollständige Abonnentenobjekt in der Nutzlast als aktuelle Darstellung des Abonnenten in Maildroppa. Gehen Sie nicht davon aus, dass nur eine bestimmte Eigenschaft geändert wurde.

Tag-Zuweisungen und -Entfernungen haben eigene Ereignistypen und können daher separat verarbeitet werden.

Abonnent abgemeldet — subscriber.unsubscribed

Wird gesendet, wenn der Abonnent durch eine Abmeldeaktion in den Status „abgemeldet“ wechselt.

Verwenden Sie dieses Ereignis, um den Kontakt in verbundenen Systemen zu unterdrücken. Melden Sie die Person nicht automatisch wieder an, nur weil ein anderes System den Kontakt weiterhin als aktiv markiert.

Tag hinzugefügt — subscriber.tag_added

Wird gesendet, wenn einem Abonnenten ein Tag zugewiesen wird.

Die Nutzlast enthält den Abonnenten und das Tag, die an dieser bestimmten Änderung beteiligt sind.

Tag entfernt — subscriber.tag_removed

Wird gesendet, wenn ein Tag von einem Abonnenten entfernt wird.

Die Nutzlast enthält den aktualisierten Abonnenten und das entfernte Tag. Das entfernte Tag wird separat bereitgestellt, obwohl es nicht mehr im aktuellen tags-Array des Abonnenten enthalten ist.

Formular übermittelt — form.submitted

Wird gesendet, wenn ein Besucher ein Maildroppa-Anmeldeformular übermittelt.

Behandeln Sie dies als Signal für eine Formularübermittlung, nicht als Bestätigung, dass das Double-Opt-in abgeschlossen wurde. Jeder Workflow, der eine bestätigte Anmeldung erfordert, muss weiterhin den aktuellen Status des Abonnenten und den Bestätigungsprozess berücksichtigen.

Separate Endpunkte für unterschiedliche Zuständigkeiten verwenden

Sie können verschiedene Ereignisse an unterschiedliche Systeme senden. Zum Beispiel:

• Senden Sie Abonnenten- und Tag-Ereignisse an ein CRM.
• Senden Sie Abmeldeereignisse an einen Unterdrückungsdienst.
• Senden Sie Formularübermittlungen an eine Analysepipeline.

Separate Endpunkte verringern unnötigen Datenverkehr und erleichtern die Fehlerdiagnose. Jeder Endpunkt verfügt über eine eigene Ereignisauswahl, URL, benutzerdefinierte Header, einen eigenen Aktivstatus, Tests und einen eigenen Zustellverlauf.

Benutzerdefinierte Header hinzufügen

Benutzerdefinierte Header sind optional. Verwenden Sie sie, wenn der Empfänger einen API-Schlüssel, Bearer-Token, Mandantenbezeichner oder einen anderen festen Header benötigt.

Klicken Sie auf „Header hinzufügen“ und geben Sie anschließend den Header-Namen und den Header-Wert ein. Geeignete Beispiele sind:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Sie können bis zu 20 benutzerdefinierte Header hinzufügen.

Header-Namen:

• sind erforderlich.
• dürfen bis zu 128 Zeichen enthalten.
• müssen gültige Zeichen für HTTP-Header-Namen verwenden.
• müssen unabhängig von Groß- und Kleinschreibung eindeutig sein.

Header-Werte:

• sind erforderlich.
• dürfen bis zu 2.000 Zeichen enthalten.
• dürfen keine Zeilenumbrüche enthalten.

Die folgenden Namen sind reserviert und können nicht durch einen benutzerdefinierten Header ersetzt werden:

• Content-Type
• Content-Length
• Host
• User-Agent
• Jeder Name, der mit X-Maildroppa- beginnt

Dadurch wird verhindert, dass ein benutzerdefinierter Wert die Zustell- und Signatur-Header von Maildroppa ersetzt.

Speicherung von Header-Geheimnissen

Maildroppa verschlüsselt benutzerdefinierte Header-Werte vor der Speicherung. Gespeicherte Werte werden dem Browser nicht in lesbarer Form zurückgegeben.

Wenn Sie den Endpunkt später bearbeiten, zeigt das Wertefeld „Gespeicherter Wert bleibt erhalten“ an. Lassen Sie es leer, wenn das bestehende Geheimnis unverändert bleiben soll. Geben Sie einen neuen Wert ein, um es zu ersetzen.

Wenn Sie den Header-Namen ändern, geben Sie den Wert erneut ein. Maildroppa behält ein gespeichertes Geheimnis nur bei, solange sein ursprünglicher Header-Name unverändert bleibt.

Durch das Entfernen einer Header-Zeile wird dieser Header nach dem Speichern des Endpunkts aus zukünftigen Zustellungen entfernt.

Benutzerdefinierte Header-Werte werden in gespeicherten Anfrageinformationen als vertraulich behandelt. Sie werden im Zustellverlauf maskiert statt angezeigt.

Endpunkt aktivieren oder deaktivieren

Lassen Sie „Aktiv“ ausgewählt, wenn der Endpunkt sofort Ereignisse empfangen soll.

Deaktivieren Sie die Auswahl, wenn Sie die Konfiguration speichern möchten, ohne Zustellungen zu starten. Sie können den Endpunkt später in der Endpunktliste aktivieren.

Ein inaktiver Endpunkt:

• empfängt keine neu auftretenden Ereignisse.
• kann keinen Webhook-Test senden.
• bleibt sichtbar und bearbeitbar.
• behält seinen vorhandenen Zustellverlauf bei.

Durch die Aktivierung eines Endpunkts werden keine Ereignisse nachträglich zugestellt, die während seiner Inaktivität aufgetreten sind.

Klicken Sie auf „Speichern“, wenn URL, Ereignisauswahl, Header und Status korrekt sind.

Endpunktliste verstehen

Jede Endpunktzeile zeigt:

• die Ziel-URL.
• ein Aktiv- oder Inaktiv-Badge.
• die abonnierten Ereignistypen.
• die Anzahl der benutzerdefinierten Header.
• den Zeitpunkt der letzten Aktualisierung des Endpunkts.

Die verfügbaren Aktionen sind:

• Ein/Aus — Aktiviert oder deaktiviert den Endpunkt.
• Test — Sendet eine sofortige Testanfrage an einen aktiven Endpunkt.
• Bearbeiten — Ändert URL, Ereignisse, Header oder Aktivstatus.
• Löschen — Entfernt die Endpunktkonfiguration nach Bestätigung dauerhaft.

Wählen Sie den Hauptbereich einer Zeile aus, um den Zustellverlauf dieses Endpunkts unterhalb der Liste zu öffnen.

Auswirkungen gespeicherter Änderungen auf bestehende Zustellungen

Ein Kontoereignis erstellt eine Zustellung mit einer Momentaufnahme der Endpunkt-URL, der Nutzlast und der benutzerdefinierten Header zu diesem Zeitpunkt.

Das Bearbeiten der URL oder der benutzerdefinierten Header wirkt sich auf neu erstellte Zustellungen aus. Eine bereits in die Warteschlange eingereihte Zustellung behält ihr ursprüngliches Ziel und ihre gespeicherte Header-Konfiguration.

Eine Änderung der ausgewählten Ereignisse wirkt sich ebenfalls nur auf danach auftretende Ereignisse aus. Maildroppa erstellt keine rückwirkenden Zustellungen für Ereignistypen, die zum Zeitpunkt des Ereignisses nicht ausgewählt waren.

Das Signaturgeheimnis ist anders: Es wird gelesen, wenn die HTTP-Anfrage vorbereitet wird. Eine ausstehende Zustellung oder erneute Wiedergabe kann daher ein neu rotiertes Signaturgeheimnis verwenden, selbst wenn ihre Nutzlast und Endpunkt-Momentaufnahme früher erstellt wurden.

Endpunkt testen

Klicken Sie bei einem aktiven Endpunkt auf „Test“, nachdem Empfänger und Signaturgeheimnis bereit sind.

Maildroppa sendet sofort eine signierte Anfrage mit der gespeicherten Endpunkt-URL und den gespeicherten benutzerdefinierten Headern. Nicht gespeicherte Änderungen in einem geöffneten Editor sind nicht Bestandteil des Tests.

Die Testnutzlast verwendet den Ereignistyp webhook.test und setzt livemode auf false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Die generierten IDs und der Zeitstempel unterscheiden sich bei jedem echten Test.

Ein Test führt genau einen HTTP-Versuch aus. Testzustellungen werden nicht in den Produktions-Wiederholungsplan aufgenommen und können nicht erneut abgespielt werden.

Nach Abschluss der Anfrage zeigt das Ergebnisfenster:

• Test erfolgreich oder Test fehlgeschlagen
• Ereignis-ID
• HTTP-Status, wenn eine Antwort empfangen wurde
• Dauer
• Zustell-ID
• Fehlerinformationen, sofern verfügbar
• einen Antwortauszug, wenn der Empfänger einen Body zurückgegeben hat

Der Test erscheint auch im Zustellverlauf mit einem Test-Badge. Verwenden Sie den Filter „Test“, um nur Testanfragen anzuzeigen.

Produktionsnutzlast verstehen

Produktionsereignisse des Kontos verwenden eine gemeinsame JSON-Hülle:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Die Eigenschaften der obersten Ebene bedeuten:

• id — Die Ereignis-ID. Sie entspricht X-Maildroppa-Event-Id.
• type — Der im Endpunkt-Editor ausgewählte Ereignisschlüssel.
• schema_version — Die Version des Nutzlastschemas. Verwenden Sie sie bei der Entscheidung, wie das Ereignis geparst werden soll.
• created_at — Der Zeitpunkt, zu dem die Ereignisnutzlast erstellt wurde, in UTC.
• livemode — true für Produktionsereignisse und false für Testereignisse.
• data — Der ereignisspezifische Inhalt.

Leiten Sie Ereignisse anhand des exakten type-Werts weiter. Ignorieren Sie zusätzliche Eigenschaften, die Ihre Integration nicht benötigt, damit kompatible Ergänzungen der Nutzlast den Empfänger nicht beeinträchtigen.

Nutzlast von Abonnentenereignissen

Abonnentenereignisse enthalten die aktuelle Darstellung des Abonnenten innerhalb von data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields und tags sind Arrays. Sie können leer sein. Eine Abonnenteneigenschaft kann auch null sein, wenn kein Wert vorhanden ist. Ihr Empfänger sollte daher dem Nutzlastschema folgen und nicht voraussetzen, dass jeder optionale Profilwert vorhanden ist.

Nutzlast von Tag-Ereignissen

Tag-Ereignisse enthalten sowohl den Abonnenten als auch das Tag, das das Ereignis ausgelöst hat:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Bei subscriber.tag_removed identifiziert data.tag weiterhin das entfernte Tag, obwohl das aktuelle tags-Array des Abonnenten es nicht mehr enthält.

Ereignis-IDs, Zustell-IDs und Idempotenz

Ereignis-ID und Zustell-ID dienen unterschiedlichen Zwecken.

Ereignis-ID

Die Ereignis-ID identifiziert das Geschäftsevent. Sie erscheint in:

• der id-Eigenschaft der Nutzlast auf oberster Ebene.
• dem Anfrage-Header X-Maildroppa-Event-Id.
• dem Zustellverlauf.

Dasselbe Ereignis kann an mehrere abonnierte Endpunkte gesendet werden. Diese Zustellungen teilen sich die Ereignis-ID.

Wiederholungen und manuelle erneute Wiedergaben behalten ebenfalls die ursprüngliche Ereignis-ID. Speichern Sie verarbeitete Ereignis-IDs und gestalten Sie die Geschäftsaktion idempotent, damit eine wiederholte Anfrage keine doppelten Kontakte erstellt, keine nicht umkehrbare Aktion wiederholt und dieselbe Änderung nicht zweimal anwendet.

Zustell-ID

Die Zustell-ID identifiziert einen Zustelldatensatz. Sie erscheint in:

• dem Anfrage-Header X-Maildroppa-Delivery-Id.
• dem Zustellverlauf.

Jede Endpunktzustellung hat eine eigene Zustell-ID. Eine manuelle erneute Wiedergabe erstellt eine neue Zustell-ID und behält dabei die ursprüngliche Ereignis-ID bei.

Verwenden Sie die Zustell-ID für technische Nachverfolgung und Support. Verwenden Sie die Ereignis-ID zur geschäftlichen Deduplizierung.

Korrekte HTTP-Antwort zurückgeben

Maildroppa klassifiziert Antworten wie folgt:

• Jede 2xx-Antwort markiert die Zustellung als erfolgreich.
• 408 Request Timeout, 429 Too Many Requests und 5xx-Antworten sind vorübergehende Fehler und können wiederholt werden.
• Netzwerkfehler, die vorübergehend sein können, werden wiederholt.
• Weiterleitungen und andere 3xx-Antworten werden nicht verfolgt und als endgültige Fehler behandelt.
• Andere 4xx-Antworten werden als endgültige Fehler behandelt und nicht wiederholt.

Geben Sie 200, 202 oder 204 nur zurück, wenn das Ereignis sicher angenommen wurde. Wenn die Verarbeitung Zeit benötigt, speichern Sie das Ereignis zuerst und geben Sie eine Erfolgsmeldung zurück, bevor Sie die langsamere Arbeit asynchron ausführen.

Geben Sie keine Weiterleitung an eine andere Webhook-URL zurück. Konfigurieren Sie stattdessen die endgültige URL in Maildroppa.

Automatischer Wiederholungsplan

Produktionszustellungen können bis zu sieben HTTP-Versuche ausführen.

Nach einem wiederholbaren Fehler plant Maildroppa den nächsten Versuch mit diesen Verzögerungen:

1. Nach Versuch 1: 1 Minute
2. Nach Versuch 2: 5 Minuten
3. Nach Versuch 3: 30 Minuten
4. Nach Versuch 4: 2 Stunden
5. Nach Versuch 5: 12 Stunden
6. Nach Versuch 6: 24 Stunden

Wenn Versuch 7 weiterhin einen wiederholbaren Fehler erhält, wird die Zustellung zu „Tot“ und es wird kein weiterer automatischer Versuch geplant.

Der Zeitplan wird ab den einzelnen fehlgeschlagenen Versuchen gemessen. Die tatsächliche Zustellzeit kann etwas später liegen, da Zustellungen asynchron verarbeitet werden und zusätzlich Systemschutzlimits unterliegen.

Beheben Sie ein vorübergehendes Empfängerproblem möglichst vor dem angezeigten Zeitpunkt „Nächster Versuch“. Wenn die automatischen Versuche beendet sind, verwenden Sie „Erneut abspielen“, sobald der Empfänger wieder fehlerfrei arbeitet.

Zustellverlauf verstehen

Der Zustellverlauf gehört zum aktuell ausgewählten Endpunkt. Die Endpunkt-URL erscheint in der Abschnittsüberschrift, damit Sie bestätigen können, welchen Verlauf Sie anzeigen.

Verwenden Sie diese Filter:

• Alle — Zeigt Produktions- und Testzustellungen.
• Produktion — Zeigt nur Live-Ereigniszustellungen.
• Test — Zeigt nur manuelle Tests.

Klicken Sie auf „Aktualisieren“, um den neuesten Status abzurufen. Der Verlauf muss nicht geöffnet bleiben, während Maildroppa eine Zustellung sendet oder wiederholt.

Die Seite zeigt die neuesten 50 passenden Zustellungen für den ausgewählten Filter.

Zustellungsspalten

Jede Zeile enthält:

• Erstellt — Der Zeitpunkt, zu dem der Zustelldatensatz erstellt wurde.
• Status — Ausstehend, Erfolgreich, Fehlgeschlagen oder Tot.
• HTTP — Antwortstatus, Anzahl der Versuche, Dauer und gegebenenfalls der Zeitpunkt des nächsten Versuchs.
• Abonnent — Die E-Mail-Adresse des Abonnenten, wenn das Ereignis mit einem Abonnenten verbunden ist.
• Zustellung — Ereignistyp, Ereignis-ID und Zustell-ID.
• Aktionen — „Erneut abspielen“, wenn die Zustellung dafür berechtigt ist.

Wenn keine HTTP-Anfrage gestellt wurde, zeigt die HTTP-Spalte „Kein HTTP-Versuch“. Dies kann vorkommen, wenn Maildroppa die Anfrage vor dem Senden ablehnt, beispielsweise weil das Signaturgeheimnis fehlt oder das gespeicherte Ziel nicht mehr sicher verwendet werden kann.

Wenn verfügbar, zeigt die Zeile außerdem einen vom Empfänger zurückgegebenen Fehler und Antwortauszug. Geben Sie in einer Webhook-Antwort keine Geheimnisse oder sensiblen personenbezogenen Daten zurück, da ein Teil dieser Antwort im Zustellprotokoll des Kontos erscheinen kann.

Zustellstatus

Ausstehend bedeutet, dass die Zustellung auf ihren ersten Versuch oder einen geplanten Wiederholungsversuch wartet. „Nächster Versuch“ wird angezeigt, wenn ein weiterer Versuch geplant wurde.

Erfolgreich bedeutet, dass der Empfänger eine 2xx-Antwort zurückgegeben hat. Kein weiterer automatischer Versuch ist erforderlich.

Fehlgeschlagen bedeutet, dass die Zustellung aufgrund eines nicht wiederholbaren Problems beendet, vor einem HTTP-Versuch abgelehnt oder vor dem Senden gestoppt wurde.

Tot bedeutet, dass alle automatischen Versuche für ein wiederholbares Problem genutzt wurden, ohne eine erfolgreiche Antwort zu erhalten.

Aufbewahrung des Verlaufs

Zustelldatensätze werden für einen begrenzten Zeitraum aufbewahrt:

• Erfolgreiche Produktionszustellungen: 30 Tage
• Fehlgeschlagene Produktionszustellungen: 90 Tage
• Tote Produktionszustellungen: 90 Tage
• Testzustellungen: 30 Tage

Führen Sie eigene Integrationsprotokolle, wenn Sie einen längeren Prüfverlauf benötigen. Speichern Sie Ereignis-IDs und Zustell-IDs, aber vermeiden Sie die unnötige Speicherung von Geheimnissen.

Zustellung erneut abspielen

Klicken Sie auf „Erneut abspielen“, wenn eine abgeschlossene Produktionszustellung erneut versucht werden soll.

„Erneut abspielen“ ist für Produktionszustellungen mit dem Status „Erfolgreich“, „Fehlgeschlagen“ oder „Tot“ verfügbar. Während eine Zustellung „Ausstehend“ ist, steht die Option nicht zur Verfügung; Testzustellungen können nicht erneut abgespielt werden.

Eine erneute Wiedergabe:

• erstellt eine neue ausstehende Zustellung.
• erstellt eine neue Zustell-ID.
• behält die ursprüngliche Ereignis-ID bei.
• behält den ursprünglichen Ereignistyp und die ursprüngliche JSON-Nutzlast bei.
• verwendet die ursprüngliche gespeicherte Ziel-URL und die Momentaufnahme der benutzerdefinierten Header.
• verwendet das aktuelle Signaturgeheimnis, wenn die neue Anfrage vorbereitet wird.

Bei einer erneuten Wiedergabe wird die Nutzlast nicht aus den aktuellen Daten des Abonnenten neu erstellt. Stattdessen wird die ursprüngliche Ereignis-Momentaufnahme erneut gesendet. Dadurch bleibt die erneute Wiedergabe nachvollziehbar und ein historisches Ereignis ändert seine Bedeutung nicht unbemerkt.

Für dieselbe Quellzustellung kann jeweils nur eine erneute Wiedergabe den Status „Ausstehend“ haben. Warten Sie, bis diese Wiedergabe abgeschlossen ist, bevor Sie eine weitere anfordern.

Stellen Sie sicher, dass der Endpunkt vor der erneuten Wiedergabe aktiv ist. Wenn der Endpunkt inaktiv ist, kann die eingereihte erneute Wiedergabe nicht erfolgreich zugestellt werden.

Da ein Empfänger die Geschäftsaktion möglicherweise abgeschlossen hat, obwohl Maildroppa keine Erfolgsmeldung erhalten hat, kann eine erneute Wiedergabe zu einer doppelten Anfrage führen. Die Deduplizierung anhand der Ereignis-ID schützt das verbundene System davor, die Aktion zu wiederholen.

Endpunkt bearbeiten

Klicken Sie auf „Bearbeiten“, um URL, Ereignisauswahl, benutzerdefinierte Header oder Aktivstatus zu ändern.

Vor dem Speichern:

1. Bestätigen Sie, dass die neue URL bereits verfügbar ist.
2. Lassen Sie gespeicherte Header-Werte leer, wenn sie unverändert bleiben sollen.
3. Geben Sie für jeden umbenannten Header einen neuen Wert ein.
4. Überprüfen Sie die Ereignisauswahl, damit erforderliche Benachrichtigungen nicht versehentlich entfernt werden.
5. Speichern Sie und senden Sie einen neuen Webhook-Test.

Denken Sie daran, dass eingereihte Zustellungen ihre bestehende URL und die Momentaufnahme der benutzerdefinierten Header behalten. Testen Sie die neue Konfiguration für zukünftige Zustellungen, statt davon auszugehen, dass sie eine ältere eingereihte Anfrage ändert.

Endpunkt deaktivieren

Verwenden Sie den Ein/Aus-Schalter, wenn Sie eine Integration pausieren möchten, ohne ihre Konfiguration und ihren Verlauf zu löschen.

Wenn ein Endpunkt ausgeschaltet wird:

• werden keine neuen Ereignisse mehr für ihn eingereiht.
• werden ausstehende Zustellungen, die noch nicht zum Senden übernommen wurden, als fehlgeschlagen markiert.
• wird „Test“ deaktiviert.
• bleibt der Endpunkt zur Bearbeitung und späteren Aktivierung verfügbar.

Eine Anfrage, die zum Zeitpunkt der Deaktivierung bereits ausgeführt wird, kann weiterhin abgeschlossen werden. Überprüfen Sie nach dem Ausschalten des Endpunkts den Zustellverlauf, wenn diese Unterscheidung für Ihre Integration wichtig ist.

Während der Inaktivität verpasste Ereignisse werden bei der erneuten Aktivierung nicht nachträglich zugestellt.

Endpunkt löschen

Klicken Sie auf „Löschen“ und bestätigen Sie die Warnung, wenn der Endpunkt nicht mehr existieren soll.

Durch das Löschen wird der Endpunkt von der Seite entfernt, zukünftige Ereigniszustellungen werden gestoppt und ausstehende Zustellungen, die noch nicht zum Senden übernommen wurden, schlagen fehl.

„Löschen“ dient nicht zum vorübergehenden Pausieren. Verwenden Sie den Ein/Aus-Schalter, wenn Sie die Konfiguration oder den sichtbaren Verlauf später möglicherweise wieder benötigen.

Notieren Sie vor dem Löschen alle Ereignis-IDs oder Zustell-IDs, die Sie noch für Ihr Integrationsaudit benötigen.

Fehlerbehebung

Der Endpunkt kann nicht gespeichert werden

Überprüfen Sie, dass:

• die URL mit https:// beginnt.
• die URL einen öffentlichen Hostnamen und Port 443 verwendet.
• die URL keine Variablen, Anmeldeinformationen oder Fragmente enthält.
• mindestens ein Ereignis ausgewählt ist.
• jeder benutzerdefinierte Header einen eindeutigen Namen und einen Wert besitzt.
• reservierte Maildroppa- und HTTP-Header nicht als benutzerdefinierte Namen verwendet werden.

Test ist deaktiviert

„Test“ ist nur für einen aktiven Endpunkt verfügbar. Schalten Sie den Endpunkt ein oder bearbeiten Sie ihn und wählen Sie „Aktiv“ aus. Speichern Sie anschließend vor dem Testen.

Der Test zeigt keinen HTTP-Versuch

Generieren Sie ein Signaturgeheimnis, wenn der Status „Fehlt“ lautet. Überprüfen Sie außerdem, ob der Zielhostname öffentlich ist und weiterhin korrekt aufgelöst wird.

Eine Anfrage kann vor dem Senden abgelehnt werden, wenn ihr Geheimnis, ihre URL, benutzerdefinierten Header oder die Sicherheitsprüfung des Ziels ungültig sind.

Der Empfänger gibt 401 oder 403 zurück

Überprüfen Sie den gespeicherten Namen des benutzerdefinierten Headers und die Zugangsdaten. Bearbeiten Sie den Endpunkt und geben Sie den Wert erneut ein, wenn er geändert wurde.

Überprüfen Sie außerdem, dass der Empfänger seine eigenen API-Zugangsdaten nicht mit der Maildroppa-Signatur verwechselt. Ein benutzerdefinierter Authorization-Header und X-Maildroppa-Signature dienen unterschiedlichen Zwecken und können unabhängig voneinander geprüft werden.

Der Empfänger gibt eine Weiterleitung zurück

Maildroppa folgt keinen Weiterleitungen. Ersetzen Sie die Endpunkt-URL durch die endgültige öffentliche HTTPS-URL und testen Sie erneut.

Die Signatur stimmt nicht überein

Bestätigen Sie, dass der Empfänger:

• das aktuelle Signaturgeheimnis verwendet.
• den exakten Wert von X-Maildroppa-Timestamp verwendet.
• <timestamp>.<raw request body> signiert.
• HMAC-SHA256 und eine Ausgabe in Kleinbuchstaben im Hexadezimalformat verwendet.
• den vollständigen Wert einschließlich v1= vergleicht.
• den Vergleich durchführt, bevor das Parsen des JSON den Body verändert.

Dasselbe Ereignis trifft mehr als einmal ein

Dies kann nach einer Netzwerkunterbrechung, einer Wiederholung oder einer manuellen erneuten Wiedergabe vorkommen. Für Webhook-Zustellsysteme ist eine Zustellung mindestens einmal statt genau einmal normal.

Verwenden Sie die Ereignis-ID als Idempotenzschlüssel. Geben Sie eine 2xx-Antwort zurück, wenn eine bereits verarbeitete Ereignis-ID erneut empfangen wird und keine zusätzliche Aktion erforderlich ist.

Eine Zustellung ist ausstehend

Sehen Sie in der HTTP-Spalte unter „Nächster Versuch“ nach. Ein wiederholbarer 408-, 429-, 5xx- oder vorübergehender Netzwerkfehler bleibt ausstehend, bis der nächste geplante Versuch erfolgt.

Klicken Sie nach dem Zeitpunkt des nächsten Versuchs auf „Aktualisieren“, um den neuesten Status zu laden.

Eine Zustellung ist tot

Alle automatischen Versuche wurden verwendet. Beheben Sie zuerst den Empfänger, stellen Sie sicher, dass der Endpunkt aktiv ist, senden Sie einen Webhook-Test und verwenden Sie anschließend „Erneut abspielen“ für die Produktionszustellung.

Empfohlene Checkliste für die Produktion

Bevor Sie sich in der Produktion auf einen Endpunkt verlassen, bestätigen Sie alle folgenden Punkte:

1. Der Empfänger verwendet eine stabile öffentliche HTTPS-URL mit einem gültigen Zertifikat.
2. Das Signaturgeheimnis wird außerhalb des Quellcodes gespeichert.
3. Die Signatur wird anhand des unveränderten Raw-Bodys geprüft.
4. Alte Zeitstempel werden entsprechend einer dokumentierten Toleranz abgelehnt.
5. Der Empfänger speichert und dedupliziert Ereignis-IDs.
6. Der Empfänger protokolliert Ereignis-IDs und Zustell-IDs zur Nachverfolgung.
7. Langsame Verarbeitung erfolgt erst, nachdem das Ereignis dauerhaft angenommen wurde.
8. Eine 2xx-Antwort wird nur für angenommene Ereignisse zurückgegeben.
9. Benutzerdefinierte Zugangsdaten werden in Headern statt in der URL gespeichert.
10. Es sind nur erforderliche Ereignistypen ausgewählt.
11. Ein Webhook-Test ist erfolgreich und erscheint korrekt im Zustellverlauf.
12. Eine Überwachung benachrichtigt Sie, wenn Produktionszustellungen Fehler zurückgeben.

Mit diesen Schutzmaßnahmen bietet die Webhooks-Seite beide Seiten einer zuverlässigen Integration: die sichere Zustellung von Ereignissen an Ihre Anwendung und einen übersichtlichen Betriebsverlauf innerhalb von Maildroppa.