Transloadit

Webhooks

Configurar Webhooks

Defina notify_url nas suas Assembly Instructions, no mesmo nível de steps. Assim que a Assembly atingir um estado terminal, a Transloadit envia um POST HTTP para essa URL.

Qualquer status a partir de 200 até, mas sem incluir, 300 confirma a entrega. Redirecionamentos e erros de cliente ou de servidor são tratados como falhas. Por padrão, a Transloadit tenta novamente as falhas 5 vezes, com um fator exponencial de 1,97.

Limitar o payload da Notification

Por padrão, um Webhook inclui o Assembly Status completo. Defina notification_payload como um array contendo qualquer combinação destes filtros suportados:

  • without_params: os campos brutos de instrução da Assembly de nível superior params, template e merged_params são omitidos.
  • without_result_meta_data: meta é omitido de cada arquivo em results.
  • without_results: o objeto results de nível superior é omitido.
  • without_upload_meta_data: meta é omitido de cada arquivo em uploads.
  • without_uploads: o array uploads de nível superior é omitido.

Os replays de Notification reutilizam os filtros fornecidos na requisição original da Assembly. Filtros definidos apenas em um Template não são preservados no replay, então um replay pode incluir dados omitidos da Notification inicial. Forneça notification_payload na requisição original da Assembly quando os replays precisarem usar os mesmos filtros.

Verificar a assinatura

Os Webhooks de Assembly usam o media type application/x-www-form-urlencoded. O campo transloadit contém o Assembly Status JSON serializado exato, e o campo signature contém o HMAC hexadecimal em minúsculas desse conteúdo.

Para verificar um Webhook:

  1. Leia os campos de formulário transloadit e signature sem modificar a string do payload.
  2. Calcule um digest hexadecimal HMAC-SHA1 sobre a string transloadit exata, usando o Auth Secret confiável selecionado conforme descrito abaixo.
  3. Compare o digest calculado com signature usando uma comparação timing-safe.
  4. Faça o parse de transloadit como JSON somente depois que as assinaturas coincidirem.

A Notification inicial de uma Assembly usa o Auth Secret da Auth Key que autenticou a criação dela, inclusive quando ela foi criada por um Assembly Replay. Os replays de Notification primeiro buscam a Auth Key registrada no Assembly Status como api_auth_key_id. Se essa chave não estiver registrada, não puder ser resolvida, tiver sido excluída, ou se a busca por ela falhar, o replay de Notification usa, em vez disso, o Auth Secret de quem fez a chamada autenticada do replay.

Os Assembly Replays mantêm o api_auth_key_id histórico da Assembly pai. Por exemplo, se a chave A criar uma Assembly e a chave B fizer o replay dela, a Notification inicial da nova Assembly é assinada com o segredo de B. Fazer o replay dessa Notification pode usar o segredo de A, mesmo quando B chama os dois endpoints de replay e ambas as chaves continuam ativas. Mantenha disponíveis para o seu verificador os segredos aplicáveis da Assembly pai e da criação por replay; não presuma que toda entrega de uma mesma Assembly usa o mesmo segredo.

Selecione os segredos de verificação a partir de configuração confiável no servidor, para o Workspace e a Assembly esperados, e não a partir de campos do payload não verificado. Quando mais de um segredo configurado for aplicável, aceite a requisição somente se a assinatura dela corresponder a um desses segredos confiáveis. Se nenhum corresponder, rejeite a requisição; não pule a verificação para aceitar um replay.

Diferentemente das assinaturas atuais de requisições da API, o signature do Webhook é um digest sha1 sem prefixo, por compatibilidade retroativa. Trate o payload como não confiável e rejeite a requisição quando qualquer um dos dois campos estiver ausente, quando a assinatura estiver malformada ou quando a comparação falhar.

Use um dos helpers de verificação dos nossos SDKs quando houver um disponível. Se você mesmo implementar a verificação, não reserialize o JSON já parseado antes de calcular o HMAC: os espaços em branco e a ordem das chaves do objeto fazem parte da sequência de bytes assinada.

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