Webhooks
Cadastra os endereços que recebem avisos automáticos de baixas, ocorrências e comprovantes, e acompanha o histórico de entregas e a fila de falhas.
Webhooks
A tela Integrações > Webhooks cadastra os endereços do sistema do assinante (o TMS da transportadora ou um terceiro) que recebem, automaticamente, cada baixa, ocorrência e comprovante assim que acontece. Pense em pedir à portaria: "me ligue quando o meu pacote chegar", em vez de ir lá perguntar de hora em hora.
Esta página explica a tela do portal. O passo a passo técnico completo (como o desenvolvedor verifica a assinatura, exemplos em cinco linguagens, túnel para testar na própria máquina) está no manual Criar um webhook, e a lista de eventos e campos na referência de webhooks.
Para que serve#
- Avisar o sistema do assinante em poucos segundos, sem ele precisar consultar a API toda hora.
- Escolher só os eventos que o sistema vai usar.
- Ver cada tentativa de entrega e reenviar o que falhou.
Quem vê#
Só o Administrador. Os demais perfis não têm o item no menu e, ao abrir o endereço direto, veem o aviso de acesso restrito.
Lista de webhooks#
A lista mostra Nome, URL, Eventos (a quantidade; passe o mouse para ver os nomes), Situação, Última entrega (há quanto tempo e como terminou) e Ações rápidas: ver, Enviar teste e Pausar ou Retomar. Clique na linha para abrir o detalhe. Sem nenhum webhook, a tela mostra "Nenhum webhook criado" e o botão Criar webhook.
| Situação | Significado |
|---|---|
| Ativo | Recebendo normalmente |
| Pausado | Você pausou, ou o endereço respondeu 410. Nenhuma entrega sai; os eventos ficam guardados por até 72 horas e saem na ordem quando você retomar |
| Com falhas | Há entregas falhando |
| Desativado automaticamente | Muitas entregas esgotadas seguidas; o Veltra avisa o contato técnico por e-mail. Crie outro webhook |
Como usar#
Criar um webhook#
- Clique em Criar webhook. Antes, peça ao desenvolvedor o endereço: uma URL pública que comece com
https://e responda rápido. - Preencha o formulário (veja a tabela abaixo) e clique em Criar webhook.
- Aparece a janela Guarde o segredo agora. O segredo é mostrado uma única vez. Clique em Copiar segredo, guarde em um cofre de segredos, marque Já guardei o segredo e clique em Concluir. Se tentar fechar sem guardar, a tela pergunta "Fechar sem guardar o segredo?".
- Entregue o segredo ao desenvolvedor por um meio seguro. Ele serve para conferir que cada aviso veio do Veltra.
- Clique em Enviar teste para conferir. O resultado aparece na tela: "Teste entregue: o assinante respondeu (código) em (N) ms." ou "O teste falhou: (motivo)."
Campos e filtros do formulário#
| Campo | Regra |
|---|---|
| Nome do assinante | Obrigatório, até 120 caracteres. Ex.: "TMS da matriz" |
| Quem recebe | Sistema da transportadora (TMS) ou Terceiro (embarcador, cliente) |
| Ambiente | Produção ou Teste. Não dá para trocar depois de criar. O teste aceita também http e endereço local |
| URL de destino | Em produção, endereço público com https://; endereços internos são recusados. Mensagem: "Digite um endereço público que comece com https://." |
| CNPJ do terceiro | Só para Terceiro; obrigatório; um por linha, CNPJ inteiro ou as 8 primeiras posições. O terceiro só recebe eventos das cargas desses CNPJs |
| Eventos | Marque ao menos um (há Marcar todos). Mensagem: "Escolha pelo menos um evento." |
| Enviar posição a cada | Aparece só para TMS com o evento de posições marcado: 5, 10 ou 15 minutos. Enviamos um lote por veículo, não uma mensagem por posição |
| E-mail de contato técnico | Obrigatório, até 320 caracteres. Use uma caixa que alguém lê: é por ela que o Veltra avisa se o webhook for desativado |
Os eventos são agrupados em: Baixas, Ocorrências, Chegada e saída, Comprovantes (emitido e retificado), Estado do evento 110180, Manifestos (recebido, alterado e cancelado), Posições agregadas e Km do veículo. Os dois últimos são só para o TMS. Webhooks de terceiros não incluem PDF nem canhoto, a menos que o assinante seja o tomador do frete.
Eventos de Teste nunca chegam a webhooks de Produção, e vice-versa.
Detalhe do webhook#
Ao abrir um webhook você vê três abas:
- Resumo: URL de destino, quem recebe, ambiente, e-mail de contato técnico, CNPJ do terceiro, posições, datas de criação e do último segredo, e os eventos assinados. As ações são Editar, Enviar teste, Pausar ou Retomar, Girar segredo e Excluir.
- Histórico de entregas: Horário, Evento, ID da entrega (com botão de copiar), Situação, Código HTTP, Tentativas e Duração. As situações são Entregue, Aguardando nova tentativa, Falhou, Teste e Esgotada.
- Fila de falhas: só as entregas esgotadas, com Reenviar em cada uma e Reenviar todas (N) no topo. Sem falhas, a tela diz "Nenhuma falha: todas as entregas chegaram ao assinante."
Girar o segredo#
Clique em Girar segredo e confirme. O segredo atual continua valendo por 24 horas para você trocar no sistema sem perder eventos; depois disso, só o novo vale. O novo segredo aparece uma única vez: guarde-o.
Excluir#
Clique em Excluir e confirme em Excluir webhook. O assinante deixa de receber eventos e o histórico de entregas é apagado. Entregas que estavam na fila de falhas não são reenviadas.
O que o endereço deve responder#
O sistema do assinante deve responder 2xx em poucos segundos e processar depois.
| Resposta | Resultado |
|---|---|
2xx | Entregue |
429, 5xx, demora, sem resposta, certificado inválido | Falha temporária; o Veltra tenta de novo mais tarde, por até 72 horas |
410 | A entrega esgota e o webhook fica Pausado |
3xx ou outro 4xx | Falha definitiva: sem nova tentativa, vai para a fila de falhas |
Depois de 72 horas desde a primeira tentativa, a entrega vira Esgotada e vai para a fila de falhas; nada é apagado. Corrija a causa e use Reenviar. O mesmo aviso pode chegar mais de uma vez: o sistema deve tratar pelo webhook-id.
Boas práticas#
- Marque só os eventos que o sistema vai usar.
- Use Enviar teste depois de criar e depois de mudar a URL.
- Use ao mesmo tempo a leitura incremental da API (veja Documentação da API) para conferir se nada ficou para trás.
- Gire o segredo periodicamente e guarde-o em cofre, nunca em código ou chat.
Perguntas frequentes#
Todas as entregas aparecem como esgotadas com código 401. O segredo no sistema está errado, ou o corpo foi alterado antes de verificar a assinatura. Corrija e use Reenviar todas.
O webhook ficou Pausado sem ninguém pausar. O endereço respondeu 410. Corrija o endereço e use Retomar.
O teste falhou com ENDERECO_RECUSADO. O endereço é interno; em produção, use uma URL pública com https://.