Transloadit

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 von 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 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 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.

Bei Notification-Wiederholungen werden die in der ursprünglichen Assembly-Anfrage angegebenen Filter wiederverwendet. Filter, die nur in einem Template definiert sind, bleiben bei einer Wiederholung nicht erhalten. Daher kann eine Wiederholung Daten enthalten, die in der ersten Notification weggelassen wurden. Geben Sie notification_payload in der ursprünglichen Assembly-Anfrage an, wenn Wiederholungen dieselben Filter verwenden müssen.

Die Signature überprüfen

Assembly-Webhooks verwenden den Medientyp application/x-www-form-urlencoded. Das Feld transloadit enthält das exakte serialisierte Assembly Status JSON, und das Feld signature enthält dessen hexadezimalen HMAC in 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 und verwenden Sie dabei das vertrauenswürdige Auth Secret, das wie unten beschrieben ausgewählt wurde.
  3. Vergleichen Sie den berechneten Digest mit signature mithilfe eines Timing-sicheren Vergleichs.
  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 bei einer Erstellung durch Assembly Replay. Bei Notification-Wiederholungen wird zunächst der Auth Key nachgeschlagen, der im Assembly Status als api_auth_key_id verzeichnet ist. Wenn dieser Auth Key nicht verzeichnet ist, nicht aufgelöst werden kann, gelöscht wurde oder das Nachschlagen fehlschlägt, verwendet die Notification-Wiederholung stattdessen das Auth Secret des authentifizierten Aufrufers der Wiederholung.

Assembly Replays behalten die historische api_auth_key_id der übergeordneten Assembly bei. Wenn beispielsweise Auth Key A eine Assembly erstellt und Auth Key B sie per Assembly Replay wiederholt, wird die erste Notification der neuen Assembly mit dem Auth Secret von B signiert. Bei einer Wiederholung dieser Notification kann das Auth Secret von A verwendet werden, selbst wenn B beide Replay-Endpunkte aufruft und beide Auth Keys aktiv bleiben. Halten Sie die jeweils zutreffenden Auth Secrets für die übergeordnete Assembly und für die Erstellung per Assembly Replay für Ihre Verifizierungsroutine 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 Signature mit einem dieser vertrauenswürdigen Auth Secrets übereinstimmt. Wenn keines übereinstimmt, lehnen Sie die Anfrage ab; überspringen Sie die Verifizierung nicht, um eine Wiederholung zu akzeptieren.

Im Gegensatz zu den aktuellen Signatures 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 lehnen Sie die Anfrage ab, wenn eines der beiden Felder fehlt, die Signature fehlerhaft formatiert ist oder der Vergleich fehlschlägt.

Verwenden Sie eine unserer SDK-Hilfsfunktionen zur Verifizierung, sofern verfügbar. Wenn Sie die Verifizierung selbst implementieren, serialisieren Sie das geparste JSON vor der Berechnung des HMAC nicht erneut: Leerraumzeichen und die Reihenfolge der Objektschlüssel sind Bestandteil 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)
}