O Webhook V2 avisa seu sistema quando um pedido ou rastreamento muda no Paylog. Cada endpoint escolhe quais eventos receberá, possui assinatura HMAC e mantém um histórico de entregas.
Para novas integrações, prefira o Webhook V2. O Webhook V1 continua disponível para integrações antigas em E-mails/Webhook.
Você precisa da permissão Configurar webhook para acessar esta área.
Precisa do formato completo dos eventos, exemplos de payload e código para validar a assinatura?
1. Abra a configuração
Acesse Ferramentas > Integrações, localize a seção Webhooks & Integrações e abra o cartão Webhooks V2.
Clique em Novo webhook.
2. Informe o endpoint e os eventos
Complete:
- Nome: identifique o sistema que receberá as notificações;
- URL do Webhook: informe o endereço HTTPS público que receberá requisições
POST; - Eventos: marque somente as mudanças que seu sistema precisa processar;
- Ativo: mantenha habilitado para iniciar as entregas depois da criação.
Os eventos estão separados em Pedido e Rastreamento. Você pode marcar eventos individualmente ou usar Selecionar todos em um grupo.
Clique em Criar webhook.
3. Guarde o segredo
O Paylog gera um segredo de 40 caracteres e o exibe uma única vez. Copie-o e armazene-o no ambiente seguro do sistema receptor.
Cada entrega traz a assinatura no cabeçalho X-Webhook-Signature, no formato sha256=<hex>. Valide o HMAC-SHA256 do corpo JSON bruto antes de processar o evento. A requisição também envia o cabeçalho X-Webhook-Event com o nome do evento entregue.
Não coloque o segredo no código-fonte, em tickets ou capturas de tela. Se ele for perdido ou exposto, use a ação Regenerar segredo; o valor anterior será invalidado imediatamente.
4. Responda rapidamente e evite duplicidade
Seu endpoint deve:
- validar a assinatura;
- persistir a
idempotency_key; - ignorar uma chave já processada;
- responder com qualquer status
2xxem até 30 segundos; - processar tarefas demoradas de forma assíncrona.
Respostas 3xx, 4xx, 5xx, timeouts ou erros de conexão são consideradas falhas. O Paylog tenta a entrega até quatro vezes. Depois de três ciclos completos com falha consecutiva, o endpoint é pausado automaticamente.
5. Teste e acompanhe as entregas
No cartão do webhook, use as ações para:
- enviar um evento de teste;
- abrir os logs das últimas entregas;
- editar URL ou eventos;
- ativar ou desativar o endpoint;
- regenerar o segredo;
- excluir o webhook.
O teste usa dados sintéticos do primeiro evento marcado no endpoint e envia X-Webhook-Test: true. Ele não cria um registro no histórico nem altera o contador de falhas.
Na tela de logs, cada entrega tem a ação de reenviar aquela entrega específica — útil quando seu servidor esteve fora do ar por pouco tempo e você só precisa recuperar alguns eventos.
6. O que vem no bloco de rastreamento
Todo evento traz um bloco shipment com o estado do envio. Vale conhecer três campos:
tracking_url— o link público de rastreamento do Paylog (https://ev.paylog.cash/rastreio/{codigo}). Funciona com qualquer transportadora, não pede login e já mostra a linha do tempo completa com as imagens do comprovante. É o link para enviar ao seu cliente, sem precisar montar a URL de cada transportadora.delivery_proof.image_urledelivery_proof.signature_url— as duas imagens do comprovante de entrega, quando existirem.delivery_proof.delivery_lat/delivery_lng— as coordenadas da entrega, quando a transportadora as informa.
Cada transportadora envia um conjunto diferente, e nenhuma envia tudo. A J&T Express manda as duas imagens (foto da entrega e assinatura) mais o nome do signatário, mas não manda coordenadas. Os Correios mandam a foto do recibo e as coordenadas, mas não têm assinatura eletrônica. Trate cada campo como opcional: a presença de um não garante a do outro. O comprovante também costuma chegar algumas horas depois do evento de entrega — até lá, os campos vêm null.
A lista completa de campos está na documentação técnica.
7. Reenvie eventos
A seção Reenvio por data / produto aparece assim que existe pelo menos um webhook cadastrado. Nela, escolha:
- o webhook de destino;
- a data inicial e final;
- opcionalmente, um produto;
- os eventos que devem ser reconstruídos.
O produtor pode solicitar pelo painel eventos dos últimos 30 dias. O payload reflete o estado atual do pedido. Para períodos maiores, abra um ticket com o suporte.
O reenvio em lote gera uma nova idempotency_key e emite os eventos marcados para todos os pedidos criados no intervalo. Avise quem recebe: deduplicar somente pela idempotency_key não impede o processamento duplicado nesse caso.
No reenvio em lote, os campos de rastreamento description, location e occurred_at chegam vazios e o status do rastreio é o atual do pedido, não o do evento original. Os detalhes estão na documentação técnica.