Developer Docs
Webhooks
Como o webhook público de status funciona hoje na Infiny, quando ele dispara e quais cuidados tomar para processar esse retorno com segurança.
Nesta página
Disparo
O webhook é o retorno assíncrono da operação. Ele não substitui o tracking, mas deve ser tratado como o canal principal de atualização de status.
O job NotifyOrderChange só envia o webhook quando o pedido tem public_integration_id e a integração possui webhook configurado.
Hoje esse job roda apenas em produção. Em ambiente local ou não produtivo, o callback não é disparado.
Condições para disparo
- O pedido precisa estar vinculado a uma integração pública.
- A integração pública precisa ter um webhook salvo.
- A aplicação precisa estar em produção.
Payload
O payload é simples e focado no essencial: pedido, status e dados do recebedor quando essa informação existe na operação.
Webhook de status
Quando a integração pública possui webhook configurado, o TMS envia uma notificação POST para o endpoint do parceiro a cada mudança relevante de status do pedido.
Campos enviados
| Campo | Tipo | Obrigatório | Descrição | Exemplo / default |
|---|---|---|---|---|
| orderId | string | Sim | shipping_id original do pedido enviado na criação. | — |
| status | string | Sim | Status operacional mais recente calculado pelo TMS. | — |
| receiver_name | string | Opcional | Nome de quem recebeu, quando essa informação estiver disponível. | — |
| receiver_document | string | Opcional | Documento do recebedor, quando disponível no TMS. | — |
| degree_of_kinship | string | Opcional | Grau de parentesco informado no ato da entrega, quando existir. | — |
Payload enviado ao parceiro
json{
"orderId": "ORDER-2026-000184",
"status": "delivered",
"receiver_name": "Ana Costa",
"receiver_document": "12345678900",
"degree_of_kinship": "self"
}Comportamento atual do TMS
Boas práticas
Seu endpoint precisa ser tolerante a repetição, ordem imperfeita e indisponibilidade temporária de rede.
- Trate o payload como idempotente usando orderId + status como chave mínima de deduplicação.
- Grave o payload bruto para auditoria e suporte.
- Responda rápido ao callback e mova qualquer processamento pesado para fila.
- Use o endpoint de tracking como fallback se precisar reconciliar divergências.
Webhook não substitui monitoramento
Suporte
Precisa validar um fluxo específico?
Se você estiver homologando uma integração ou precisar conferir um comportamento da API pública atual, fale com a equipe da Infiny antes de subir volume real.