Webhooks

Configurar Webhooks

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

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

A confirmação indica o recebimento, não o processamento bem-sucedido. Inspecione o estado ok ou o código error do payload verificado para distinguir Assemblies concluídas, canceladas e com falha. Um reenvio de Notification também pode entregar um Assembly Status não terminal; não presuma que toda entrega significa conclusão.

Limitar o payload da Notification

Por padrão, um Webhook inclui o Assembly Status completo. Defina notification_payload como um array que contenha qualquer combinação destes filtros compatíveis:

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

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

O esquema do payload abaixo permite essas omissões. O campo meta de um upload pode estar ausente mesmo quando o upload permanece em uploads. Os demais campos mantêm seu significado no Assembly Status. Aceite campos adicionais para manter a compatibilidade, mas não dependa de campos de diagnóstico não documentados.

Verificar a assinatura

Os Webhooks de Assembly usam o tipo de mídia application/x-www-form-urlencoded. O campo transloadit contém a string serializada exata do Assembly Status JSON, e o campo signature contém seu HMAC em hexadecimal com letras minúsculas.

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 os bytes da string exata de transloadit, usando o Auth Secret confiável selecionado conforme descrito abaixo.
3. Compare o digest calculado com signature usando uma comparação segura contra ataques de temporização.
4. Faça o parse de transloadit como JSON somente depois que as assinaturas corresponderem.

A Notification inicial de uma Assembly usa o Auth Secret da Auth Key que autenticou sua criação, inclusive quando ela foi criada por uma reexecução de Assembly. Os reenvios 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 localizada, tiver sido excluída ou sua busca falhar, o reenvio de Notification usará o Auth Secret de quem fez a chamada autenticada de reenvio.

As reexecuções de Assembly mantêm o api_auth_key_id histórico da Assembly de origem. Por exemplo, se a chave A criar uma Assembly e a chave B a reexecutar, a Notification inicial da nova Assembly será assinada com o segredo de B. O reenvio dessa Notification pode usar o segredo de A, mesmo quando B chama ambos os endpoints de reexecução e reenvio e ambas as chaves permanecem ativas. Mantenha disponíveis para o verificador os segredos aplicáveis da Assembly de origem e da criação por reexecução; não presuma que todas as entregas de uma mesma Assembly usam o mesmo segredo.

Selecione os segredos de verificação a partir de uma 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 sua assinatura corresponder a um desses segredos confiáveis. Se nenhum corresponder, rejeite a requisição; não ignore a verificação para aceitar um reenvio.

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

Use um dos auxiliares de verificação dos nossos SDKs quando disponível. Se você implementar a verificação por conta própria, não serialize novamente o JSON após o parse antes de calcular o HMAC: espaços em branco e a ordem das chaves dos objetos 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)
}

Ativar uma assinatura mais forte

Defina notification_signature_algo como sha256 ou sha384 ao criar ou atualizar uma Auth Key. Essa configuração é independente do signature_algo da chave, que controla a assinatura de requisições à API. As chaves existentes e novas têm null como padrão; omitir a configuração na atualização preserva seu valor, e defini-la como null desativa o cabeçalho adicional.

As chaves com essa opção ativada adicionam um cabeçalho Transloadit-Signature contendo sha256:<lowercase hex digest> ou sha384:<lowercase hex digest>. O campo de formulário legado signature permanece inalterado. Ambas as assinaturas abrangem os bytes UTF-8 da string JSON filtrada exata no campo de formulário transloadit decodificado, antes da codificação de URL. Não assine o corpo HTTP codificado nem faça o parse e a nova serialização do JSON antes de verificá-lo.

As Notifications iniciais usam as configurações da chave carregadas no momento da autenticação da Assembly. Alterar uma chave não altera as Assemblies já em andamento. Os reenvios explícitos de Notification buscam em conjunto o segredo atual e o algoritmo de Notification da chave registrada; as configurações de quem fez a chamada são usadas em conjunto se a busca da chave histórica recorrer à alternativa descrita acima. As novas tentativas automáticas mantêm o algoritmo selecionado e o payload serializado para aquela entrega.

Implante um verificador que reconheça o novo cabeçalho antes de ativá-lo. Quando sua integração passar a exigir a assinatura mais forte, rejeite cabeçalhos ausentes ou inválidos e rejeite algoritmos diferentes daquele configurado no seu verificador. Nunca recorra silenciosamente ao campo SHA-1. Durante a migração, implante primeiro todos os emissores de Notifications e manipuladores de reenvio. Aguarde a atualização dos caches de configurações das chaves e a conclusão das Assemblies anteriores, e confirme que o cabeçalho chega nas entregas de Assemblies criadas após a alteração antes de exigi-lo. Depois que os destinatários passarem a exigir o cabeçalho, prefira avançar o emissor para uma versão mais recente: revertê-lo para uma versão que ofereça apenas o formato legado interrompe as entregas, a menos que os destinatários primeiro restaurem a compatibilidade com Notifications apenas no formato legado.

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

A verificação da assinatura autentica o payload; ela não impede entregas duplicadas. Torne o processamento idempotente usando a identidade verificada da Assembly e o estado da própria aplicação.