Geprüft am 2026-11-11 · API-Version 2026-11-09 · Markdown lesen
Kunden-Webhooks
Ausgehende Ereignis-Zustellung für deinen Arbeitsbereich. Registriere einen HTTPS-Endpunkt, verifiziere das einmalige Signatur-Secret und empfange signierte Ereignisse mit begrenzten Wiederholungen.
Einen Endpunkt registrieren
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- Das Signatur-Secret (
whsec_…) wird einmal zurückgegeben: in der ersten erfolgreichen Erstellungsantwort. Speichere es; eine idempotente Wiederholung derselben Erstellung liefert den Endpunkt ohne das Secret zurück, und es kann nicht erneut angezeigt werden. - Ziele müssen HTTPS sein, öffentlich auflösbar und frei von eingebetteten Zugangsdaten. Anfragen an private, Loopback-, Link-Local- (einschließlich Cloud- Metadaten), Unique-Local- und Multicast-Adressen werden abgelehnt, bevor irgendeine Verbindung hergestellt wird, und Weiterleitungen werden nie gefolgt.
- Die Registrierung stellt ein gezieltes
webhook.verification-Ereignis für diesen Endpunkt in die Warteschlange, unabhängig von seinemeventTypes-Filter. Gewöhnliche Ereignisse fließen erst, nachdem dein Endpunkt die Verifizierung mit 2xx beantwortet hat.
Zustellungen verifizieren
Jede Anfrage trägt:
| Header | Bedeutung |
|---|---|
x-publisher-event-id | Stabile Ereignis-ID: identisch über Wiederholungen und Replays hinweg |
x-publisher-event-type | Ereignistyp, z. B. post.published |
x-publisher-timestamp | Unix-Sekunden |
x-publisher-signature | t=<ts>,v1=<hex> |
Die Signatur ist HMAC-SHA256 über ${t}.${event_id}.${raw_body} mit deinem
Signatur-Secret. Verifiziere mit einer Toleranz von ±300 Sekunden und lehne Replays außerhalb
dieser Toleranz ab. Node-Beispiel:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Verifiziere immer gegen den rohen Anfrage-Body, bevor du ihn parst.
Ereignis-Umschlag
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Anfänglicher Ereigniskatalog (erweiterbar; eventTypes-Filter bei der Registrierung):
webhook.verification: Challenge-Payload; antworte mit 2xx, um den Endpunkt zu aktivierenpost.published: ein Ziel mit nativem Beleg bestätigtdelivery.failed: ein Ziel ist endgültig fehlgeschlagendelivery.requires_action: Zustimmung/Erneute Verbindung/Nachprüfung erforderlich
Aggregierte Beitragsergebnisse (post.partially_published, post.failed) werden
noch nicht ausgesendet; sie werden hier erst dokumentiert, sobald ein Producer existiert, verlass dich
also nicht auf sie. Abonniere die obigen Ereignisse pro Ziel und leite den Batch-
Zustand aus den Zustellungsergebnissen des Beitrags ab.
Wiederholungen, Replay und Deaktivierung
- Versuche: sofort, dann +1m, +5m, +30m, +2h, +8h. Wiederholungen verwenden dieselbe Ereignis-ID und einen byte-identischen Body, damit du sicher deduplizieren kannst.
- 2xx = zugestellt. 429/5xx/Timeouts werden wiederholt. Andere 4xx schlagen für dieses Ereignis dauerhaft fehl (behebe den Endpunkt, dann Replay).
- 410 Gone deaktiviert den Endpunkt: Es werden keine weiteren Ereignisse für ihn in die Warteschlange gestellt.
- Operator-autorisiertes Replay über den internen Webhook-Dienst sendet ein Ereignis mit seiner ursprünglichen ID erneut. Ein aktiv geleaseter laufender Versuch wird nie entzogen; das Replay meldet, dass das Ereignis beschäftigt ist, und kann kurz darauf erneut versucht werden.
Betriebshinweise
- Zustellungsdiagnostik speichert nur sichere Ergebnis-Codes: nie dein Secret, Signaturen, Anfrage-Header oder Antwort-Bodies. Payloads werden zusätzlich bereinigt: Provider-/OAuth-Secrets und Medien-Presign-URLs werden entfernt, bevor irgendetwas in die Warteschlange gestellt wird.
- Endpunkte sind arbeitsbereichsbezogen: Der Besitz einer Endpunkt-UUID aus einem anderen Arbeitsbereich hat keine Wirkung.
- Zustellung erfolgt mindestens einmal pro akzeptierter Ereignisvorkommnis; dedupliziere über
x-publisher-event-id.
Verfügbarkeit der Entwicklertools
Die Developers-Seite listet Arbeitsbereich-API-Keys und Webhook-Endpunkte unabhängig von der Verschlüsselungskonfiguration für Signatur-Secrets auf. Das Erstellen eines Webhooks erfordert eine gültige Server-Verschlüsselungskonfiguration; bitte den Deployment-Operator, eine Konfigurationswarnung zu beheben. Die API-Key-Verwaltung bleibt verfügbar. Vorhandene Signatur- Secrets werden nie wieder angezeigt.