Webhooks

Configurar webhooks

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

Cualquier código de estado desde 200 hasta 300, sin incluir este último, confirma la entrega. Las redirecciones y los errores de cliente o de servidor se tratan como fallos. De forma predeterminada, Transloadit reintenta los fallos 5 veces con un factor exponencial de 1,97.

La confirmación indica la recepción, no que el procesamiento haya sido correcto. Consulta el estado ok o el código error de la carga útil verificada para distinguir las Assemblies completadas, canceladas y fallidas. Un reenvío de Notification también puede entregar un Assembly Status no terminal; no des por hecho que cada entrega implica que la Assembly se ha completado.

Limitar la carga útil de la Notification

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

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

Los reenvíos de Notification reutilizan los filtros proporcionados en la solicitud original de la Assembly. Los filtros definidos solo en un Template no se conservan en el reenvío, por lo que un reenvío puede incluir datos omitidos en la Notification inicial. Proporciona notification_payload en la solicitud original de la Assembly cuando los reenvíos deban usar los mismos filtros.

El esquema de carga útil que aparece a continuación permite estas omisiones. El meta de una subida puede faltar aunque la subida siga en uploads. Los demás campos conservan su significado en el Assembly Status. Acepta campos adicionales por compatibilidad, pero no dependas de campos de diagnóstico no documentados.

Verificar 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 sobre la cadena transloadit exacta, usando el Auth Secret de confianza seleccionado como se describe a continuación.
3. Compara el resumen calculado con signature mediante una comparación segura frente 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, también cuando se creó mediante una reejecución de Assembly. Los reenvíos de Notification buscan primero la Auth Key registrada en el Assembly Status como api_auth_key_id. Si esa clave no está registrada, no se puede resolver, se ha eliminado o su búsqueda falla, el reenvío de Notification usa en su lugar el Auth Secret del llamante autenticado que solicita el reenvío.

Las reejecuciones de Assembly conservan el api_auth_key_id histórico de la Assembly de origen. Por ejemplo, si la clave A crea una Assembly y la clave B la reejecuta, la Notification inicial de la nueva Assembly se firma con el secreto de B. Reenviar esa Notification puede usar el secreto de A, incluso cuando B llama a ambos endpoints (el de reejecución y el de reenvío) y ambas claves siguen activas. Mantén disponibles para tu verificador los secretos aplicables de la Assembly de origen y de la creación de la reejecución; no des por hecho que todas las entregas de una misma Assembly usan el mismo secreto.

Selecciona los secretos 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 se aplique más de un secreto configurado, acepta la solicitud solo si su Signature coincide con uno de esos secretos de confianza. Si ninguno coincide, rechaza la solicitud; no omitas la verificación para aceptar un reenvío.

A diferencia de las Signatures actuales de las solicitudes a la API, la signature del webhook es un resumen sha1 sin prefijo, por compatibilidad con versiones anteriores. Trata la carga útil como no fiable y rechaza la solicitud cuando falte alguno de los dos campos, la Signature tenga un formato incorrecto o la comparación falle.

Usa una de las funciones auxiliares de verificación de nuestros SDK cuando esté disponible. Si implementas la verificación tú mismo, 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)
}