Skip to main content

Testar um webhook

POST /v2/webhooks/{idEndpoint}/testar Cria e envia um log de teste para cada evento que o webhook assina, com o código real do evento e um payload de exemplo que tem exatamente os mesmos campos do payload real, preenchidos com dados fictícios. Use para validar, antes de ir para produção, se o seu sistema recebe, autentica e interpreta o evento.
  • O envio é síncrono: acontece dentro da própria requisição, sem passar pela fila. A resposta já traz o resultado de cada envio.
  • O envelope tem o campo teste: true (eventos reais não têm este campo).
  • Headers e token são os mesmos de um envio real (X-Gestio-Event traz o código do evento).
  • O teste funciona mesmo com o webhook inativo, para você validar antes de ativá-lo.
  • O log de teste é tentado uma única vez, sem novas tentativas automáticas.
  • O resultado não altera o contador de falhas nem a desativação automática do webhook — nem mesmo quando o teste tem sucesso.
  • Cada envio respeita o tempo limite de 10 segundos. Com vários eventos assinados, os envios são feitos em sequência e a resposta traz os logs na ordem dos eventos.
Resposta (200) — um log por evento assinado, já com o resultado do envio:
O campo envelope é o JSON exato enviado ao seu sistema, em formato texto. Use JSON.parse (ou equivalente) para ler o conteúdo.
Se o seu sistema recusar o envio de teste (erro, tempo limite ou resposta diferente de 2xx), a rota continua respondendo 200 com success: true: a falha do destino aparece no log, com situacao: "Falha", ultimoStatusHttp e ultimoErro. A falha do destino não é falha do teste.
Payload de exemplo de compras.pedido-de-compra.processado:

Erros do teste

Logs

GET /v2/webhooks/{idEndpoint}/logs Lista os logs de um webhook de forma paginada.
string
Filtra pela situação: Pendente, Entregue ou Falha.
string (date-time)
Data inicial de criação do log.
string (date-time)
Data final de criação do log.
integer
default:"0"
Quantidade de registros a pular.
integer
Quantidade de registros da página. Máximo de 500.
string
Campo de ordenação: criadoEm, entregueEm, tipoDoEvento, situacao, tentativas, ultimoStatusHttp ou ultimaTentativaEm.
boolean
Ordenação decrescente.
Exemplo:
Resposta (200):

Campos do log

string (uuid)
Identificador da entrega (igual ao id do envelope).
string (uuid)
Webhook do log.
string
Código do evento.
string
URL usada neste envio (a do webhook no momento em que o log foi criado).
string
Pendente, Entregue ou Falha.
integer
Quantidade de tentativas já feitas.
integer | null
HTTP da última resposta do seu sistema; null se não houve resposta (ex.: tempo limite).
string | null
Erro da última tentativa (até 500 caracteres); null após sucesso.
integer | null
Duração da última tentativa, em milissegundos.
string (date-time) | null
Data da última tentativa, em UTC.
string (date-time) | null
Próxima tentativa agendada; null quando o log terminou.
string (date-time)
Data de criação do log.
string (date-time) | null
Data em que o seu sistema confirmou o recebimento.
Apenas o resultado da última tentativa é guardado; cada nova tentativa sobrescreve o anterior. O corpo da resposta do seu sistema não é gravado.

Consultar um log

GET /v2/webhooks/logs/{idLog} devolve o log com os mesmos campos acima e mais o campo envelope, com o JSON exato enviado. Um idLog inexistente ou de outra empresa responde 404.

Reenviar um log

POST /v2/webhooks/logs/{idLog}/reenviar Reenvia um log em qualquer situação (Pendente, Entregue ou Falha), útil depois de corrigir um problema no seu sistema.
  • A entrega mantém o mesmo idEntrega e o mesmo envelope, por isso o seu tratamento de duplicidade continua funcionando.
  • É enviado para a URL gravada no log, mesmo que a URL do webhook tenha sido alterada depois.
  • Usa o token atual do webhook (se o token foi rotacionado, vai o novo).
  • Volta para Pendente com tentativas = 0, sem o resultado da tentativa anterior, e segue as mesmas regras de novas tentativas.
  • O reenvio é assíncrono: a resposta confirma o enfileiramento. Consulte GET /v2/webhooks/logs/{idLog} para acompanhar o resultado.
  • Um log de teste reenviado continua sendo de teste (teste: true).
Para reprocessar várias falhas de uma vez, liste com GET /v2/webhooks/{idEndpoint}/logs?situacao=Falha e chame o reenvio para cada idEntrega — respeitando o limite de requisições por minuto da API.