O webhook v1 continua ativo para os produtores que utilizam esse contrato. Ele envia notificações de rastreio e entrega para as URLs cadastradas na página E-mails e Webhook.
As URLs existentes do webhook v1 continuam funcionando e podem ser consultadas, testadas, adicionadas ou removidas em E-mails e Webhook. Para novas integrações, recomendamos Webhooks v2, que oferece eventos adicionais, assinatura HMAC, histórico de tentativas, reenvio e pausa automática. O contrato v1 documentado nesta página permanece sem assinatura e sem garantia de reentrega.
Eventos disponíveis
Cada tipo de evento possui sua própria configuração. Se houver mais de uma URL no mesmo evento, o sistema envia uma requisição separada para cada URL.
| Evento | Origem no sistema | Pedidos de amostra | Particularidade |
|---|---|---|---|
| Código de rastreio recebido | RastreioRecebido ou RastreioMarketplaceRecebido |
Não são enviados | Inclui transportadora. |
| Pedido entregue | PedidoEntregue |
Também podem ser enviados | Não inclui transportadora no payload real. |
O corpo não possui um campo de evento e a requisição real não envia X-Webhook-Event. Identifique o evento pela URL configurada para cada tipo.
Contrato de entrega
| Propriedade | Comportamento real |
|---|---|
| Método | POST |
| Corpo | JSON no envelope {"dados": {...}} |
Content-Type |
application/json |
| Timeout de resposta | 10 segundos |
| Timeout de conexão | 5 segundos |
| Sucesso | A resposta é registrada no log da aplicação, sem validação para reenvio. |
| HMAC | Não há assinatura HMAC no webhook v1 do produtor. |
| Reenvio automático | Não há reenvio efetivo. Erros de conexão e respostas não-2xx são absorvidos pela execução legada. |
| Pausa automática | Não existe. |
| Histórico de entregas | Não existe no painel v1. |
Trate o webhook v1 como uma notificação best effort. Embora o job possua metadados de tentativas, a implementação legada não propaga falhas HTTP ou de conexão para a fila; por isso, não ocorre uma nova tentativa automática.
Payload de rastreio
Exemplo de uma requisição real quando o código de rastreio fica disponível:
{
"dados": {
"pedido_id": 12345,
"cpf_cliente": "123.456.789-00",
"nome_cliente": "João da Silva",
"email_cliente": "[email protected]",
"telefone_cliente": "(11) 99999-9999",
"cod_transacao": "ABC123",
"plataforma": "Braip",
"cod_rastreio": "AA123456789BR",
"transportadora": "CORREIOS",
"referencia_externa": "pedido-987"
}
}
Payload de pedido entregue
O evento de entrega usa o mesmo envelope, mas o payload real não contém a chave transportadora:
{
"dados": {
"pedido_id": 12345,
"cpf_cliente": "123.456.789-00",
"nome_cliente": "João da Silva",
"email_cliente": "[email protected]",
"telefone_cliente": "(11) 99999-9999",
"cod_transacao": "ABC123",
"plataforma": "Braip",
"cod_rastreio": "AA123456789BR",
"referencia_externa": "pedido-987"
}
}
Semântica dos campos
Nesta página:
- Sempre: a chave existe no payload real daquele evento; o valor pode ser
nullquando indicado. - Condicional: a chave só existe no evento indicado.
- Opcional: a chave pode não existir na requisição.
| Campo | Tipo | Presença | Pode ser null ou vazio |
Semântica |
|---|---|---|---|---|
dados |
objeto | Sempre | Não | Envelope do webhook v1. |
dados.pedido_id |
inteiro | Sempre | Não | ID interno do pedido no Paylog. |
dados.cpf_cliente |
string ou null |
Sempre | Sim | CPF/CNPJ salvo no cliente. |
dados.nome_cliente |
string ou null |
Sempre | Sim | Nome do cliente. |
dados.email_cliente |
string ou null |
Sempre | Sim | E-mail do cliente. |
dados.telefone_cliente |
string ou null |
Sempre | Sim | Celular; quando ausente, usa o telefone. |
dados.cod_transacao |
string ou null |
Sempre | Sim | Código da transação na plataforma de origem. |
dados.plataforma |
string | Sempre | Não | Nome resolvido da integração do pedido. Não é um enum público fechado. |
dados.cod_rastreio |
string | Sempre | Pode ser "" |
Código de rastreio convertido para string. |
dados.transportadora |
string | Condicional: somente rastreio | Não | Nome da transportadora ou nome de exibição do canal. |
dados.referencia_externa |
string ou null |
Sempre | Sim | Referência externa informada ao criar o pedido. |
O valor de plataforma e o nome de transportadora vêm dos cadastros atuais do pedido. Não dependa de uma lista fixa de nomes; armazene-os como strings.
Teste pelo painel
O botão de teste faz uma chamada direta, com timeout de 10 segundos, e considera qualquer resposta 2xx bem-sucedida. Ele não usa fila, não cria histórico de entrega, não tenta novamente e não afeta pausa automática.
Além de Content-Type: application/json, a instalação padrão envia:
X-PayLog-Test: true
O nome do header é montado a partir do nome configurado da aplicação (X-{NomeDaAplicação}-Test).
{
"dados": {
"pedido_id": "TEST-12345",
"cpf_cliente": "123.456.789-00",
"nome_cliente": "Cliente Teste",
"email_cliente": "[email protected]",
"telefone_cliente": "(11) 99999-9999",
"cod_transacao": "TESTabc123def456",
"plataforma": "Manual",
"cod_rastreio": "TEST123456789BR",
"transportadora": "CORREIOS",
"referencia_externa": "test_xyz789"
}
}
O teste é sintético, não byte a byte idêntico à produção: pedido_id começa com TEST-; no teste de Pedido Entregue, cod_rastreio e transportadora são enviados como strings vazias, enquanto a entrega real omite transportadora.