Webhooks

Configurar Webhooks

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

Qualquer status a partir de 200 e abaixo de 300 confirma a entrega. Redirecionamentos e erros de cliente ou de servidor são tratados como falhas. Por padrão, a Transloadit faz 5 novas tentativas em caso de falha, 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 com qualquer combinação destes filtros compatíveis:

• without_params: os campos brutos de instrução da Assembly no 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 reenvios de Notification reutilizam os filtros fornecidos na requisição original da Assembly. Filtros definidos apenas em um Template não são preservados no reenvio, então 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 schema do payload abaixo permite essas omissões. O meta de um upload pode estar ausente mesmo quando o upload permanece em uploads. Os demais campos mantêm o significado que têm no Assembly Status. Aceite campos adicionais por compatibilidade, mas não dependa de campos de diagnóstico não documentados.

Verificar a assinatura

Os Webhooks de Assembly usam o media type application/x-www-form-urlencoded. O campo transloadit contém exatamente o Assembly Status JSON serializado, e o campo signature contém o HMAC hexadecimal dele, em 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 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 resistente a ataques de temporizaçã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 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 resolvida, tiver sido excluída ou se a busca por ela falhar, o reenvio da Notification usará, em vez disso, o Auth Secret do chamador autenticado que solicitou o reenvio.

As reexecuções de Assembly mantêm o api_auth_key_id histórico da Assembly pai. Por exemplo, se a Chave A cria uma Assembly e a Chave B a reexecuta, a Notification inicial da nova Assembly é assinada com o segredo de B. O reenvio dessa Notification pode usar o segredo de A, mesmo quando B chama tanto o endpoint de reexecução quanto o de reenvio 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 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 lado do 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 ignore a verificação para aceitar um reenvio.

Ao contrário das assinaturas atuais de requisições de 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 algum dos campos estiver ausente, a assinatura estiver malformada ou a comparação falhar.

Use um dos helpers de verificação dos nossos SDKs quando houver um disponível. Se você implementar a verificação por conta própria, não serialize novamente 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)
}