Diagnóstico
Falhas e reenvio
Entenda quando uma entrega de webhook é considerada falha, como reenviar eventos e como evitar duplicidade de processamento.
A operação não depende do webhook
Se a entrega do webhook falhar, a operação no SmartPOS continua com o resultado final registrado. A falha afeta apenas a notificação para o sistema integrado.
Sem retentativa infinita
Eventos com falha ficam disponíveis para diagnóstico e reenvio pelo portal do parceiro. A API não deve ficar tentando indefinidamente contra um endpoint indisponível.
Quando a entrega é aceita
| Campo | Tipo | Descrição |
|---|---|---|
| HTTP 2xx | sucesso | O evento foi aceito pelo endpoint da integração. |
| HTTP 4xx | falha | O endpoint rejeitou o evento por autenticação, validação ou regra própria. |
| HTTP 5xx | falha | O endpoint respondeu com erro interno ou indisponibilidade. |
| timeout | falha | O endpoint não respondeu dentro do tempo esperado. |
Como reenviar com segurança
| Campo | Tipo | Descrição |
|---|---|---|
| 1 | corrigir | Corrija URL, token, firewall, DNS, certificado ou indisponibilidade do endpoint. |
| 2 | reenviar | Use o portal do parceiro para reenviar o evento depois da correção. |
| 3 | deduplicar | Use id e dados.referencia para ignorar eventos já processados. |
| 4 | auditar | Registre status HTTP, horário e payload para conciliação e suporte. |
Idempotência obrigatória no reenvio
O mesmo evento pode chegar mais de uma vez. Grave o id do evento e trate o processamento como idempotente.
Reenvio via portal
A lista de eventos no portal do parceiro é temporária e serve para diagnóstico. Corrija a causa da falha antes de reenviar.