Transloadit

Webhooks

Configura los webhooks

Establece notify_url en tus Assembly Instructions, al mismo nivel que steps. Una vez que la Assembly alcanza un estado terminal, Transloadit envía una solicitud HTTP POST a esa URL.

Cualquier código de estado desde 200 hasta, pero sin incluir, 300 confirma la entrega. Las redirecciones y los errores del cliente o del servidor se consideran fallos. De forma predeterminada, Transloadit reintenta las entregas fallidas 5 veces con un factor exponencial de 1,97.

Limita la carga útil de la Notification

De forma predeterminada, un webhook incluye el Assembly Status completo. Establece notification_payload en un array que contenga cualquier combinación de estos filtros admitidos:

  • without_params: se omiten los campos sin procesar de nivel superior de las Assembly Instructions: params, template y merged_params.
  • without_result_meta_data: se omite meta de cada archivo de results.
  • without_results: se omite el objeto results de nivel superior.
  • without_upload_meta_data: se omite meta de cada archivo de uploads.
  • without_uploads: se omite el array uploads de nivel superior.

Las repeticiones de Notifications reutilizan los filtros proporcionados en la solicitud original de la Assembly. Los filtros definidos únicamente en un Template no se conservan al repetir la Notification, por lo que una repetición puede incluir datos omitidos en la Notification inicial. Proporciona notification_payload en la solicitud original de la Assembly cuando las repeticiones deban usar los mismos filtros.

Verifica la Signature

Los webhooks de Assembly usan el tipo de medio application/x-www-form-urlencoded. El campo transloadit contiene el Assembly Status JSON serializado exacto, y el campo signature contiene su HMAC hexadecimal en minúsculas.

Para verificar un webhook:

  1. Lee los campos de formulario transloadit y signature sin modificar la cadena de la carga útil.
  2. Calcula un resumen hexadecimal HMAC-SHA1 de la cadena exacta de transloadit, usando el Auth Secret de confianza seleccionado como se describe a continuación.
  3. Compara el resumen calculado con signature mediante una comparación resistente a ataques de temporización.
  4. Analiza transloadit como JSON solo después de que las Signatures coincidan.

La Notification inicial de una Assembly usa el Auth Secret de la Auth Key que autenticó su creación, incluso cuando se creó mediante un Assembly Replay. Las repeticiones de Notifications primero buscan la Auth Key registrada en el Assembly Status como api_auth_key_id. Si esa Auth Key no está registrada, no se puede resolver, se ha eliminado o su búsqueda falla, la repetición de la Notification usa en su lugar el Auth Secret de quien realiza la llamada autenticada de repetición.

Los Assembly Replays conservan el valor histórico de api_auth_key_id de la Assembly de origen. Por ejemplo, si la Auth Key A crea una Assembly y la Auth Key B la repite, la Notification inicial de la nueva Assembly se firma con el Auth Secret de B. Al repetir esa Notification, se puede usar el Auth Secret de A, incluso cuando B llama a ambos endpoints de repetición y ambas Auth Keys siguen activas. Mantén a disposición de tu verificador los Auth Secrets aplicables de la Assembly de origen y de la creación mediante Assembly Replay; no asumas que todas las entregas de una misma Assembly usan el mismo Auth Secret.

Selecciona los Auth Secrets de verificación a partir de una configuración de confianza del lado del servidor para el Workspace y la Assembly esperados, no a partir de campos de la carga útil sin verificar. Cuando sea aplicable más de un Auth Secret configurado, acepta la solicitud solo si su Signature coincide con uno de esos Auth Secrets de confianza. Si no coincide con ninguno, rechaza la solicitud; no omitas la verificación para aceptar una repetición.

A diferencia de las Signatures actuales de las solicitudes a la API, el campo signature del webhook es un resumen sha1 sin prefijo por compatibilidad con versiones anteriores. Trata la carga útil como no confiable y rechaza la solicitud si falta cualquiera de los dos campos, si la Signature tiene un formato incorrecto o si la comparación falla.

Usa una de las funciones auxiliares de verificación de nuestros SDK cuando esté disponible. Si implementas la verificación por tu cuenta, no vuelvas a serializar el JSON analizado antes de calcular el HMAC: los espacios en blanco y el orden de las claves de los objetos forman parte de la secuencia de bytes firmada.

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)
}