Webhooks
Receba uma mensagem assinada assim que uma execução termina, sem consultar de novo para baixar o arquivo
Um webhook é um endereço seu que a DocTransform chama toda vez que uma das suas execuções termina. Pense numa campainha: em vez de perguntar sem parar se a execução acabou, você espera, e a DocTransform toca quando ela acaba. Esse toque é uma mensagem curta chamada evento. Ele diz qual execução terminou e dá um link para o arquivo.
Criar um webhook
Você precisa de uma coisa só: um endereço que comece com https:// e que possa ser acessado pela internet. Uma ferramenta como o Zapier dá um, e o seu próprio servidor também.
Abra o cartão Webhooks
Vá à sua página de conta e ache o cartão Webhooks. Clique em Adicionar Webhook.
Cole o seu endereço
Cole-o em Endereço para enviar os eventos. Uma execução terminou e Uma execução falhou já vêm marcados, e Para todos os modelos também. Mude só se precisar.
Salve e envie um teste
Clique em Salvar Webhook e depois em Enviar evento de teste. A resposta aparece no Registro de entregas da mesma tela, e assim você sabe que funciona antes de uma execução de verdade.
Copie o segredo de assinatura
Só se o seu próprio código vai conferir os eventos: em Segredo de assinatura, clique em Mostrar e depois em Copiar. Quem usa Zapier, Make ou n8n pode pular este passo.
Você pode ter até 5 webhooks, igual em todos os planos. Os webhooks são gerenciados só na página de conta, não pela API. As entregas nunca contam na sua cota.
GET /runs/{id} continua funcionando e não vai desaparecer. Você escreve código? Leia Verificar webhooks. UsaZapier, Make ou n8n? Você só precisa do endereço que essas ferramentas dão.O que chega
Cada evento é um POST com um corpo JSON de três partes: type, timestamp (quando a execução terminou) e data. Toda chave está sempre presente e vale null quando não se aplica, para que uma ferramenta mapeie os mesmos campos sempre. Nunca vai conteúdo do arquivo, colunas, nomes de arquivo ou nomes de modelo: para os detalhes, consulte GET /runs/{id}.
run.succeeded é enviado quando o arquivo está pronto:
{
"type": "run.succeeded",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-30T10:15:00Z",
"error": null
}
}run.failed é enviado quando uma execução termina sem arquivo. Não tem link, e error.code é um dos códigos de erro:
{
"type": "run.failed",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "failed",
"download_url": null,
"expires_at": null,
"error": {
"code": "PIPELINE_FAILED",
"message": "The pipeline failed while running the Template."
}
}
}webhook.test é o que Enviar evento de teste envia. O link dele não funciona, então ignore-o com if type == "webhook.test":
{
"type": "webhook.test",
"timestamp": "2026-09-27T10:15:00+00:00",
"data": {
"run_id": "run_test",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-28T10:15:00+00:00",
"error": null
}
}Conferir que um evento é verdadeiro
Qualquer pessoa que descubra o seu endereço poderia mandar dados a ele. Cada evento leva uma assinatura que só a DocTransform e você podem gerar, e assim o seu código distingue um evento verdadeiro de um falso. Verificar webhooks mostra como, com exemplos para copiar.
Novas tentativas e desativação
Um evento só conta como entregue quando o seu endereço responde com um status 2xx em até 10 segundos. Redirecionamentos não são seguidos. Todo o resto é tentado de novo, então uma queda curta do seu lado não perde nada. Depois de cada tentativa que falha, a DocTransform espera mais:
| Depois da tentativa que falhou | Espera até a próxima |
|---|---|
| 1 | 1 min |
| 2 | 5 min |
| 3 | 30 min |
| 4 | 2 h |
| 5 | 6 h |
| 6 | 12 h |
| 7 | 24 h |
| 8 | 18 h |
São 9 tentativas em cerca de 2,6 dias (62 h 36 min, mais ou menos 10 %). Que um evento já tratado se repita é normal: veja Impedir repetições e duplicatas.
Quando as entregas falham
O webhook continua ativo e mostra que está falhando. Abra o seu Registro de entregas para ver cada tentativa e o motivo. Você recebe um e-mail depois de 24 horas falhando. Quando o seu endereço voltar a responder, a próxima tentativa entrega o evento.
O registro de entregas dá a cada tentativa que falhou um destes motivos:
| Motivo | Em palavras simples | O que fazer |
|---|---|---|
WEBHOOK_UNREACHABLE | Não conseguimos chegar ao seu endereço: ele não existe, está offline ou nos recusou. | Confira se o endereço não tem erros e se o seu receptor está funcionando. |
WEBHOOK_TIMEOUT | O seu endereço levou mais de 10 segundos para responder. | Responda primeiro e faça o trabalho lento depois. |
WEBHOOK_REJECTED | O seu endereço respondeu, mas com um erro em vez de um status 2xx. | Veja o registro do seu receptor para saber por que ele disse não. |
WEBHOOK_REDIRECTED | O seu endereço nos mandou para outro endereço, e isso nunca seguimos. | Cole o endereço final no lugar. |
WEBHOOK_URL_BLOCKED | O endereço aponta para uma rede privada, então paramos de enviar para ele. | Use um endereço https público. Para testar no seu próprio computador, veja Testar webhooks localmente. |
WEBHOOK_SECRET_UNREADABLE | Não conseguimos ler o segredo de assinatura do webhook, então nada foi enviado. | Abra o webhook e clique em Alterar segredo. |
WEBHOOK_DISABLED | O webhook estava desligado, então o evento não foi enviado. | Clique em Ativar. |
Quando um webhook se desativa
Depois de 10 tentativas falhas seguidas, espalhadas por mais de 5 dias, o webhook fica Desativado e você recebe um segundo e-mail. Nada mais é enviado. Conserte o seu endereço e clique em Ativar: ele oferece reenviar as entregas que foram paradas ao desativá-lo, dos últimos 3 dias. Uma execução que terminou enquanto o webhook estava desativado não é enviada: pegue o arquivo dela com GET /runs/{id}/output, ou pelo link de download enquanto ele durar. Você também pode clicar em Reenviar numa entrega específica.
Quando o seu endereço responde «sumiu»
Se o seu endereço responde 410 Gone, o webhook se desativa na hora, porque essa resposta quer dizer que ele não volta. Isso acontece muito quando um Zap ou cenário é apagado ou fica desligado. Coloque o receptor de volta no ar e clique em Ativar.
Baixar o arquivo
download_url baixa o arquivo sem chave de API até expires_at. Isso é 3 dias depois que a execução terminou quando um webhook a recebe, e 30 minutos nos outros casos, que é também o tempo de GET /runs/{id}/output. Vale null em run.failed e numa entrega enviada depois que o arquivo expirou, como um Reenviar tardio. Um link expirado responde DOWNLOAD_LINK_EXPIRED: execute o modelo de novo.
Testar webhooks localmente
A DocTransform envia só para endereços https públicos, então localhost é recusado. Um túnel dá ao seu servidor local um endereço público. Este não precisa de conta:
cloudflared tunnel --url http://localhost:8000Cole em um webhook o endereço que ele mostra, mais o seu caminho, e clique em Enviar evento de teste. O ngrok faz o mesmo trabalho. Apague o webhook quando terminar, porque o endereço do túnel muda toda vez.
Ver o que aconteceu
Atividade da API, na sua página de conta, lista cada requisição feita pelas suas chaves de API nos últimos 90 dias, inclusive as recusadas. O Registro de entregas de cada webhook mostra cada tentativa com a sua resposta e um botão Reenviar. Os dois se ligam pelo id da execução: clique em Ver esta execução para ir de um ao outro.