AiVideoEditor
Kostenlos starten
Menü

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 seinem eventTypes-Filter. Gewöhnliche Ereignisse fließen erst, nachdem dein Endpunkt die Verifizierung mit 2xx beantwortet hat.

Zustellungen verifizieren

Jede Anfrage trägt:

HeaderBedeutung
x-publisher-event-idStabile Ereignis-ID: identisch über Wiederholungen und Replays hinweg
x-publisher-event-typeEreignistyp, z. B. post.published
x-publisher-timestampUnix-Sekunden
x-publisher-signaturet=<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 aktivieren
  • post.published: ein Ziel mit nativem Beleg bestätigt
  • delivery.failed: ein Ziel ist endgültig fehlgeschlagen
  • delivery.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.