Versionierung und Kompatibilität

MailLand ändert Webhook-Payloads nur so, dass ein bestehender Empfänger die Änderung ignorieren kann. Diese Seite beschreibt dieses Versprechen, die Kennungen und Zeitstempel, auf die sich ein Empfänger verlassen kann, und was geschieht, bevor überhaupt etwas Inkompatibles eingeführt werden könnte.

SchemaversionLink zum Abschnitt kopieren

Jeder Ereignistyp hat eine Schemaversion seines Payloads, eine positive ganze Zahl. Alle Ereignisse haben heute die Version 1.

• Der Body enthält sie als schema_version.
• Der Header X-MLND-Event-Version enthält denselben Wert.
• Ein Body ohne schema_version (gesendet, bevor es das Feld gab) hat die Version 1.

Die Version wird beim Erzeugen des Ereignisses festgelegt; jede Wiederholung desselben Ereignisses trägt also dieselbe Version. Das v1 in X-MLND-Signature ist die Version des Signaturverfahrens und davon unabhängig.

KennungenLink zum Abschnitt kopieren

Deduplizieren Sie über event_id, nie über die Zustell-ID. Ereignisse können mehrfach und in anderer Reihenfolge eintreffen; ordnen Sie Nachrichtenereignisse nach data.status_version, das für eine Nachricht nur steigt.

ZeitstempelLink zum Abschnitt kopieren

Alle Zeiten im Body sind UTC im Format ISO 8601 mit abschließendem Z. Der Body ist bei jeder Wiederholung identisch; nur die Header eines Versuchs ändern sich. Die Signatur deckt t und den rohen Body ab, nicht die übrigen Header; behandeln Sie diese als Routing-Metadaten und vertrauen Sie dem Body.

KompatibilitätsversprechenLink zum Abschnitt kopieren

Empfänger müssen unbekannte JSON-Felder und HTTP-Header ignorieren. Unter dieser Regel ist jede der folgenden Änderungen sicher und erfolgt ohne neue Schemaversion:

• ein neues Feld im Body oder in data oder ein neuer Header;
• ein neuer Ereignistyp, den Sie erst nach einem Abonnement erhalten;
• ein neuer Wert in einem Feld, das diese Dokumentation als offen erweiterbar beschreibt.

Jede der folgenden Änderungen ist inkompatibel und wird an einer bestehenden Version nie vorgenommen:

• ein Feld, Header oder Ereignistyp wird entfernt oder umbenannt;
• Typ, Format, Einheit oder Bedeutung eines Felds ändern sich;
• ein optionales Feld wird Pflicht oder ein Feld ohne Null wird nullbar;
• ein neuer Wert in einem Feld, das als geschlossene Liste dokumentiert ist.

Eine inkompatible Änderung erschiene nur als neue Schemaversion, die Sie ausdrücklich wählen. Bestehende Abonnements werden nie automatisch auf eine neue Version umgestellt.

AbkündigungsrichtlinieLink zum Abschnitt kopieren

• Eine Abkündigung wird mindestens 180 Tage vor jeder verlangten Umstellung angekündigt: im Changelog, im Dashboard und per E-Mail an die Inhaber des Kontos.
• Die Ankündigung nennt das genaue Ereignis, die Version oder das Feld, den Ersatz und den Umstellungsweg.
• Ein abgekündigtes Feld bleibt im Payload, ein abgekündigtes Ereignis bleibt für bestehende Abonnenten verfügbar. Eine Abkündigung allein entfernt nie etwas. Das Entfernen einer Version erfordert eine eigene Ankündigung, frühestens 180 Tage nach der Abkündigung.

AusnahmenLink zum Abschnitt kopieren

Webhook-Schritte von AutomationenLink zum Abschnitt kopieren

Die Webhook-Schritte einer Automation werden genau wie Kunden-Webhooks signiert: Prüfen Sie X-MLND-Signature mit dem Signaturgeheimnis des Empfängers dieses Schritts nach denselben Schritten.

• Jeder Empfänger (eine eigene Schritt-URL) hat ein eigenes Geheimnis, sodass kein Empfänger Signaturen erzeugen kann, die ein anderer akzeptiert. Schritte, die an dieselbe URL senden, sind ein Empfänger und teilen sich dessen Geheimnis.
• Lesen Sie die Geheimnisse mit GET /v1/marketing/automations/{id}/webhook-signing-secrets: eine Liste secrets aus { webhookUrl, secret } in Schrittreihenfolge. Sie entstehen, wenn eine Automation mit Webhook-Schritt erstellt oder gespeichert wird. Eine Bearbeitung behält das Geheimnis jeder unveränderten URL; eine neue oder geänderte URL erhält ein neues Geheimnis.
• Ersetzen Sie sie mit POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate: Jeder Empfänger erhält ein neues Geheimnis, und alle werden zurückgegeben. Die alten Geheimnisse gelten sofort nicht mehr; lassen Sie jeden Empfänger daher vorher beide akzeptieren. Eine Kopie einer Automation erhält eigene Geheimnisse, und eine Automation, deren Webhook-Schritte alle entfernt werden, verliert sie.
• Um nur einen Empfänger zu rotieren, senden Sie { "webhookUrl": "<Schritt-URL>" } als Body der Regenerate-Anfrage; alle anderen Empfänger behalten ihr Geheimnis. Eine URL, die keine Webhook-Schritt-URL der Automation ist, ergibt 400.
• Eine Automation, deren Empfänger sich noch ein Geheimnis teilen, wird beim Aktivieren oder Fortsetzen oder vor dem nächsten Webhook-Schritt in Geheimnisse pro Empfänger aufgeteilt. Eine Anfrage wird nie mit einem Geheimnis signiert, das ein anderer Empfänger besitzt: Gelingt die Aufteilung nicht, wird der Schritt nicht gesendet.
• X-MLND-Event-Id ist für eine Ausführung eines Schritts für einen Abonnenten stabil. Nutzen Sie es zusammen mit dem 5-Minuten-Fenster für t, um Wiederholungsangriffe abzuweisen.
• Eine Automation, die gespeichert wurde, bevor es Signaturen gab, sendet unsignierte Anfragen, bis sie erneut gespeichert oder ihr Geheimnis neu erzeugt wird.
• Diese Anfragen sind Best Effort: ein Versuch, kein Wiederholungsplan. Die Automation läuft weiter, unabhängig von der Antwort des Empfängers.