Webhooks

Webhooks konfigurieren

Legen Sie notify_url in Ihren Assembly Instructions auf derselben Ebene wie steps fest. Sobald die Assembly einen Endzustand erreicht, sendet Transloadit einen HTTP-POST an diese URL.

Jeder Status ab 200 und unter 300 bestätigt die Zustellung. Weiterleitungen sowie Client- und Serverfehler gelten als fehlgeschlagene Zustellungen. Standardmäßig wiederholt Transloadit fehlgeschlagene Zustellungen 5-mal mit einem exponentiellen Faktor von 1,97.

Die Bestätigung belegt den Empfang, nicht die erfolgreiche Verarbeitung. Prüfen Sie den ok-Status oder den error-Code der verifizierten Nutzdaten, um abgeschlossene, abgebrochene und fehlgeschlagene Assemblies zu unterscheiden. Das erneute Senden einer Notification kann auch einen Assembly Status übermitteln, der noch keinen Endzustand erreicht hat. Gehen Sie nicht davon aus, dass jede Zustellung den Abschluss bedeutet.

Nutzdaten der Notification begrenzen

Standardmäßig enthält ein Webhook den vollständigen Assembly Status. Setzen Sie notification_payload auf ein Array, das eine beliebige Kombination dieser unterstützten Filter enthält:

• without_params: Die unverarbeiteten Felder params, template und merged_params der Assembly Instructions auf oberster Ebene werden weggelassen.
• without_result_meta_data: meta wird bei jeder Datei in results weggelassen.
• without_results: Das Objekt results auf oberster Ebene wird weggelassen.
• without_upload_meta_data: meta wird bei jeder Datei in uploads weggelassen.
• without_uploads: Das Array uploads auf oberster Ebene wird weggelassen.

Beim erneuten Senden einer Notification werden die Filter aus der ursprünglichen Assembly-Anfrage wiederverwendet. Filter, die nur in einem Template definiert sind, bleiben beim erneuten Senden nicht erhalten. Daher können dabei Daten enthalten sein, die in der ursprünglichen Notification weggelassen wurden. Geben Sie notification_payload in der ursprünglichen Assembly-Anfrage an, wenn beim erneuten Senden dieselben Filter verwendet werden müssen.

Das unten stehende Nutzdatenschema lässt diese Auslassungen zu. Das Feld meta eines Uploads kann fehlen, obwohl der Upload weiterhin in uploads enthalten ist. Die übrigen Felder behalten ihre Bedeutung im Assembly Status. Akzeptieren Sie aus Kompatibilitätsgründen zusätzliche Felder, aber verlassen Sie sich nicht auf undokumentierte Diagnosefelder.

Signatur überprüfen

Assembly-Webhooks verwenden den Medientyp application/x-www-form-urlencoded. Das Feld transloadit enthält das exakt serialisierte Assembly Status JSON, und das Feld signature enthält dessen HMAC als hexadezimalen Wert mit Kleinbuchstaben.

So überprüfen Sie einen Webhook:

1. Lesen Sie die Formularfelder transloadit und signature, ohne die Nutzdaten-Zeichenfolge zu verändern.
2. Berechnen Sie einen hexadezimalen HMAC-SHA1-Digest über die exakte transloadit-Zeichenfolge. Verwenden Sie dazu das vertrauenswürdige Auth Secret, das Sie wie unten beschrieben auswählen.
3. Vergleichen Sie den berechneten Digest mit signature mithilfe eines gegen Timing-Angriffe abgesicherten Vergleichs.
4. Parsen Sie transloadit erst als JSON, nachdem die Signaturen übereinstimmen.

Die ursprüngliche Notification einer Assembly verwendet das Auth Secret des Auth Keys, mit dem ihre Erstellung authentifiziert wurde. Das gilt auch, wenn sie durch eine erneute Ausführung einer Assembly erstellt wurde. Beim erneuten Senden einer Notification wird zunächst der im Assembly Status als api_auth_key_id erfasste Auth Key nachgeschlagen. Wenn dieser Key nicht erfasst wurde, nicht aufgelöst werden kann, gelöscht wurde oder das Nachschlagen fehlschlägt, verwendet das erneute Senden der Notification stattdessen das Auth Secret des authentifizierten Aufrufers.

Bei der erneuten Ausführung einer Assembly bleibt die historische api_auth_key_id der übergeordneten Assembly erhalten. Wenn beispielsweise Key A eine Assembly erstellt und Key B sie erneut ausführt, wird die ursprüngliche Notification der neuen Assembly mit dem Auth Secret von B signiert. Beim erneuten Senden dieser Notification kann das Auth Secret von A verwendet werden, selbst wenn B beide Endpunkte für die erneute Ausführung beziehungsweise das erneute Senden aufruft und beide Keys weiterhin aktiv sind. Halten Sie die jeweils zutreffenden Auth Secrets des übergeordneten Auth Keys und des Auth Keys, mit dem die neue Assembly erstellt wurde, für Ihren Verifizierer bereit. Gehen Sie nicht davon aus, dass jede Zustellung für eine Assembly dasselbe Auth Secret verwendet.

Wählen Sie die Auth Secrets für die Verifizierung aus einer vertrauenswürdigen serverseitigen Konfiguration für den erwarteten Workspace und die erwartete Assembly aus, nicht aus Feldern der ungeprüften Nutzdaten. Wenn mehr als ein konfiguriertes Auth Secret infrage kommt, akzeptieren Sie die Anfrage nur, wenn ihre Signatur mit einem dieser vertrauenswürdigen Auth Secrets übereinstimmt. Wenn keines übereinstimmt, weisen Sie die Anfrage zurück. Überspringen Sie die Überprüfung nicht, um ein erneutes Senden zu akzeptieren.

Anders als aktuelle Signaturen für API-Anfragen ist die Webhook-signature aus Gründen der Abwärtskompatibilität ein sha1-Digest ohne Präfix. Behandeln Sie die Nutzdaten als nicht vertrauenswürdig und weisen Sie die Anfrage zurück, wenn eines der beiden Felder fehlt, die Signatur fehlerhaft formatiert ist oder der Vergleich fehlschlägt.

Verwenden Sie einen unserer SDK-Helfer zur Signaturprüfung, sofern verfügbar. Wenn Sie die Prüfung selbst implementieren, serialisieren Sie das geparste JSON vor der HMAC-Berechnung nicht erneut: Leerraum und die Reihenfolge der Objektschlüssel sind Teil der signierten Bytefolge.

import { createHmac, timingSafeEqual } from 'node:crypto'

// authSecret must come from trusted server-side configuration.
function verifyTransloaditWebhook({ authSecret, payload, signature }) {
  if (typeof payload !== 'string' || typeof signature !== 'string') return false
  if (!/^[0-9a-f]+$/.test(signature)) return false

  const expected = createHmac('sha1', authSecret).update(payload, 'utf8').digest()
  if (signature.length !== expected.length * 2) return false
  const received = Buffer.from(signature, 'hex')

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

Stärkere Signatur aktivieren

Setzen Sie notification_signature_algo beim Erstellen oder Aktualisieren eines Auth Keys auf sha256 oder sha384. Diese Einstellung ist unabhängig von signature_algo des Keys, das die Signierung von API-Anfragen steuert. Bei bestehenden und neuen Keys ist null der Standardwert. Wenn Sie die Einstellung bei einer Aktualisierung weglassen, bleibt sie erhalten. Wenn Sie sie auf null setzen, wird der zusätzliche Header deaktiviert.

Keys, für die diese Option aktiviert ist, fügen einen Transloadit-Signature-Header hinzu, der sha256:<lowercase hex digest> oder sha384:<lowercase hex digest> enthält. Das bisherige Formularfeld signature bleibt unverändert. Beide Signaturen decken die UTF-8-Bytes der exakten gefilterten JSON-Zeichenfolge im decodierten Formularfeld transloadit vor der URL-Codierung ab. Signieren Sie nicht den codierten HTTP-Body und parsen und serialisieren Sie das JSON vor der Überprüfung nicht erneut.

Ursprüngliche Notifications verwenden die Key-Einstellungen, die bei der Authentifizierung der Assembly geladen werden. Eine Änderung an einem Key ändert nichts an Assemblies, die bereits verarbeitet werden. Beim expliziten erneuten Senden einer Notification werden das aktuelle Auth Secret und der aktuelle Notification-Algorithmus des erfassten Keys gemeinsam nachgeschlagen. Wenn wie oben beschrieben auf den Aufrufer zurückgegriffen wird, werden dessen Einstellungen gemeinsam verwendet. Automatische Wiederholungsversuche behalten den ausgewählten Algorithmus und die serialisierten Nutzdaten für diese Zustellung bei.

Stellen Sie einen Verifizierer bereit, der den neuen Header versteht, bevor Sie ihn aktivieren. Sobald Ihre Integration die stärkere Signatur verlangt, weisen Sie Anfragen mit fehlendem oder ungültigem Header sowie Algorithmen zurück, die nicht dem in Ihrem Verifizierer konfigurierten Algorithmus entsprechen. Fallen Sie niemals stillschweigend auf das SHA-1-Feld zurück. Stellen Sie bei der Migration zuerst alle Absender von Notifications und Handler für deren erneutes Senden bereit. Lassen Sie die Caches für Key-Einstellungen aktualisieren und frühere Assemblies abschließen. Bestätigen Sie außerdem, dass der Header bei Zustellungen für Assemblies ankommt, die nach der Änderung erstellt wurden, bevor Sie ihn verlangen. Sobald Empfänger den Header verlangen, ziehen Sie ein Rollforward des Absenders vor: Ein Rollback auf einen Build, der nur die bisherige Signatur unterstützt, unterbricht die Zustellung, sofern die Empfänger nicht zuvor die Kompatibilität mit Notifications wiederherstellen, die nur die bisherige Signatur enthalten.

import { createHmac, timingSafeEqual } from 'node:crypto'

// expectedAlgorithm and authSecret come from trusted server-side configuration.
function verifyStrongTransloaditWebhook({ authSecret, expectedAlgorithm, payload, signature }) {
  if (expectedAlgorithm !== 'sha256' && expectedAlgorithm !== 'sha384') return false
  if (typeof payload !== 'string' || typeof signature !== 'string') return false
  const prefix = `${expectedAlgorithm}:`
  if (!signature.startsWith(prefix)) return false
  const hex = signature.slice(prefix.length)
  if (!/^[0-9a-f]+$/.test(hex)) return false
  const expected = createHmac(expectedAlgorithm, authSecret).update(payload, 'utf8').digest()
  if (hex.length !== expected.length * 2) return false
  return timingSafeEqual(Buffer.from(hex, 'hex'), expected)
}

Die Signaturprüfung authentifiziert die Nutzdaten; sie verhindert keine doppelten Zustellungen. Gestalten Sie die Verarbeitung idempotent und verwenden Sie dazu die verifizierte Assembly-Identität und den eigenen Zustand Ihrer Anwendung.