Webhooks

Webhooks konfigurieren

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

Jeder Status ab 200 bis ausschließlich 300 bestätigt die Zustellung. Weiterleitungen sowie Client- oder Serverfehler werden als Fehlschläge behandelt. 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 Payload, um abgeschlossene, abgebrochene und fehlgeschlagene Assemblies zu unterscheiden. Ein erneutes Senden einer Notification kann auch einen Assembly Status zustellen, der keinen Endzustand darstellt. Gehen Sie nicht davon aus, dass jede Zustellung den Abschluss bedeutet.

Notification-Payload begrenzen

Standardmäßig enthält ein Webhook den vollständigen Assembly Status. Setzen Sie notification_payload auf ein Array mit einer beliebigen Kombination dieser unterstützten Filter:

• without_params: Die rohen Felder der Assembly Instructions auf oberster Ebene, params, template und merged_params, 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 von Notifications werden die Filter wiederverwendet, die in der ursprünglichen Assembly-Anfrage angegeben wurden. Filter, die nur in einem Template definiert sind, bleiben beim erneuten Senden nicht erhalten. Eine erneut gesendete Notification kann daher Daten enthalten, 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 gelten müssen.

Das unten stehende Payload-Schema erlaubt diese Auslassungen. Upload-meta kann auch dann fehlen, wenn der Upload in uploads verbleibt. Andere Felder behalten ihre Bedeutung aus dem Assembly Status. Akzeptieren Sie aus Kompatibilitätsgründen zusätzliche Felder, verlassen Sie sich aber nicht auf undokumentierte Diagnosefelder.

Signature verifizieren

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 in hexadezimaler Kleinschreibung.

So verifizieren Sie einen Webhook:

1. Lesen Sie die Formularfelder transloadit und signature, ohne den Payload-String zu verändern.
2. Berechnen Sie einen hexadezimalen HMAC-SHA1-Digest über den exakten transloadit-String und verwenden Sie dabei das vertrauenswürdige Auth Secret, das wie unten beschrieben ausgewählt wird.
3. Vergleichen Sie den berechneten Digest mithilfe eines timing-sicheren Vergleichs mit signature.
4. Parsen Sie transloadit erst dann als JSON, wenn die Signatures übereinstimmen.

Die erste Notification einer Assembly verwendet das Auth Secret des Auth Keys, der ihre Erstellung authentifiziert hat, auch wenn sie durch eine erneute Ausführung einer Assembly erstellt wurde. Beim erneuten Senden einer Notification wird zuerst der Auth Key nachgeschlagen, der im Assembly Status als api_auth_key_id erfasst ist. Wenn dieser Auth Key nicht erfasst ist, 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, der das erneute Senden anfordert.

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 erste Notification der neuen Assembly mit dem Secret von B signiert. Beim erneuten Senden dieser Notification kann das Secret von A verwendet werden, selbst wenn B beide Endpunkte (für die erneute Ausführung und für das erneute Senden) aufruft und beide Keys aktiv bleiben. Halten Sie die jeweils zutreffenden Secrets der übergeordneten Assembly und der Erstellung durch erneute Ausführung für Ihren Verifier verfügbar. Gehen Sie nicht davon aus, dass jede Zustellung für eine Assembly dasselbe Secret verwendet.

Wählen Sie die 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 unverifizierten Payload. Wenn mehr als ein konfiguriertes Secret in Frage kommt, akzeptieren Sie die Anfrage nur, wenn ihre Signature mit einem dieser vertrauenswürdigen Secrets übereinstimmt. Wenn keines übereinstimmt, lehnen Sie die Anfrage ab. Überspringen Sie die Verifizierung nicht, um eine erneut gesendete Notification zu akzeptieren.

Anders als aktuelle Signatures von API-Anfragen ist die Webhook-signature aus Gründen der Abwärtskompatibilität ein sha1-Digest ohne Präfix. Behandeln Sie die Payload als nicht vertrauenswürdig und lehnen Sie die Anfrage ab, wenn eines der beiden Felder fehlt, die Signature fehlerhaft formatiert ist oder der Vergleich fehlschlägt.

Verwenden Sie, sofern verfügbar, eine unserer SDK-Hilfsfunktionen zur Verifizierung. Wenn Sie die Verifizierung selbst implementieren, serialisieren Sie das geparste JSON nicht erneut, bevor Sie den HMAC berechnen: Whitespace 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)
}