DocTransform

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.

  1. Abra o cartão Webhooks

    Vá à sua página de conta e ache o cartão Webhooks. Clique em Adicionar Webhook.

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

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

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

Nota Consultar 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 falhouEspera até a próxima
11 min
25 min
330 min
42 h
56 h
612 h
724 h
818 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:

MotivoEm palavras simplesO que fazer
WEBHOOK_UNREACHABLENã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_TIMEOUTO seu endereço levou mais de 10 segundos para responder.Responda primeiro e faça o trabalho lento depois.
WEBHOOK_REJECTEDO 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_REDIRECTEDO seu endereço nos mandou para outro endereço, e isso nunca seguimos.Cole o endereço final no lugar.
WEBHOOK_URL_BLOCKEDO 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_UNREADABLENão conseguimos ler o segredo de assinatura do webhook, então nada foi enviado.Abra o webhook e clique em Alterar segredo.
WEBHOOK_DISABLEDO 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.

Atenção Qualquer pessoa com o link pode baixar o arquivo até ele expirar. Não cole o link em nenhum lugar compartilhado.

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:8000

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