Webhooks

Configurar Webhooks

Establece 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, 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.

La confirmación indica la recepción, no que el procesamiento se haya completado correctamente. Inspecciona 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 una Notification también puede entregar un Assembly Status no terminal; no supongas que cada entrega significa que el procesamiento ha finalizado.

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

Los reenvíos de Notifications reutilizan los filtros proporcionados en la solicitud original de la Assembly. Los filtros definidos únicamente en un Template no se conservan al reenviar, 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 la carga útil que aparece a continuación permite estas omisiones. El campo meta de una carga puede estar ausente incluso cuando el archivo cargado sigue presente en uploads. Los demás campos conservan su significado en el Assembly Status. Acepta campos adicionales para mantener la compatibilidad, pero no dependas de campos de diagnóstico no documentados.

Verificar la firma

Los Webhooks de las Assemblies usan el tipo de medio application/x-www-form-urlencoded. El campo transloadit contiene la cadena serializada exacta del Assembly Status JSON, 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 los bytes exactos de la cadena 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 de tiempo constante.
4. Analiza transloadit como JSON solo después de que las firmas 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 una reejecución de una Assembly. Los reenvíos de Notifications 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 la Notification usa en su lugar el Auth Secret del solicitante autenticado del reenvío.

Las reejecuciones de Assemblies 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. El reenvío de esa Notification puede usar el secreto de A, incluso cuando B llama a ambos endpoints de reenvío y reejecución y ambas claves siguen activas. Mantén disponibles para tu verificador los secretos aplicables de la Assembly de origen y de la creación mediante reejecución; no supongas que todas las entregas de una 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 sea aplicable más de un secreto configurado, acepta la solicitud solo si su firma coincide con uno de esos secretos de confianza. Si no coincide con ninguno, rechaza la solicitud; no omitas la verificación para aceptar un reenvío.

A diferencia de las firmas actuales de las solicitudes de API, el campo signature del Webhook es un resumen sha1 sin prefijo por motivos de compatibilidad con versiones anteriores. Trata la carga útil como no confiable y rechaza la solicitud cuando falte cualquiera de los dos campos, la firma 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 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)
}

Optar por una firma más robusta

Establece notification_signature_algo en sha256 o sha384 al crear o actualizar una Auth Key. Esta configuración es independiente del signature_algo de la clave, que controla la firma de las solicitudes de API. Las claves existentes y las nuevas tienen null como valor predeterminado; omitir esta configuración al actualizar conserva su valor, y establecerla en null desactiva la cabecera adicional.

Las claves en las que se habilita esta opción añaden una cabecera Transloadit-Signature que contiene sha256:<lowercase hex digest> o sha384:<lowercase hex digest>. El campo de formulario heredado signature permanece sin cambios. Ambas firmas abarcan los bytes UTF-8 de la cadena JSON filtrada exacta contenida en el campo de formulario transloadit decodificado, antes de la codificación de URL. No firmes el cuerpo HTTP codificado ni analices y vuelvas a serializar el JSON antes de verificarlo.

Las Notifications iniciales usan la configuración de la clave cargada cuando se autentica la Assembly. Cambiar una clave no modifica las Assemblies que ya están en curso. Los reenvíos explícitos de Notifications consultan conjuntamente el secreto actual de la clave registrada y su algoritmo de notificación; la configuración del solicitante se usa en conjunto si la búsqueda de la clave histórica recurre a la alternativa descrita anteriormente. Los reintentos automáticos conservan el algoritmo seleccionado y la carga útil serializada para esa entrega.

Despliega un verificador que reconozca la nueva cabecera antes de habilitarla. Cuando tu integración requiera la firma más robusta, rechaza las solicitudes con una cabecera ausente o no válida y rechaza los algoritmos distintos del configurado en tu verificador. Nunca recurras silenciosamente al campo SHA-1. Durante la migración, despliega primero todos los emisores de notificaciones y los controladores de reenvío. Deja que las cachés de configuración de las claves se actualicen y que las Assemblies anteriores finalicen, y confirma que la cabecera llegue en las entregas de las Assemblies creadas después del cambio antes de exigirla. Una vez que los receptores exijan la cabecera, es preferible actualizar el emisor a una versión posterior: revertirlo a una compilación que solo admita el formato heredado interrumpe la entrega a menos que los receptores restablezcan primero la compatibilidad con las notificaciones que solo usan el formato heredado.

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

La verificación de la firma autentica la carga útil; no evita las entregas duplicadas. Haz que el procesamiento sea idempotente usando la identidad verificada de la Assembly y el estado propio de la aplicación.