Webhooks v2

Webhooks v2 entregam eventos de pedido e rastreamento em endpoints configurados em Ferramentas → Integrações → Webhooks. Cada endpoint pertence ao produtor autenticado e assina os eventos escolhidos no painel.

#Requisição HTTP

Cada evento é enviado por POST, com JSON e timeout de resposta de 30 segundos.

#Eventos disponíveis

#Pedido

#Rastreamento

#Versão do schema

meta.api_version identifica a forma do corpo e só muda quando o schema muda. A versão atual é 2.

#Full-schema e nulabilidade

O corpo possui schema completo: as chaves documentadas existem em todos os eventos. Dados indisponíveis são null, objetos conhecidos mantêm sua forma e items pode ser uma lista vazia. Valores monetários *_cents são inteiros em centavos.

Nesta página:

• Sempre: a chave existe em todo payload; a coluna de nulabilidade informa se o valor pode ser null.
• Condicional: a chave existe, mas só recebe objeto ou dado quando a condição é satisfeita; caso contrário vale null.
• Opcional: a chave ou header pode ser omitido. No corpo v2, nenhuma chave do schema é opcional.

#Campos raiz

#order

#shipment

Quando preenchido, collection_address contém sempre estas nove chaves, cada uma podendo ser null:

#Exemplo completo: shipment.awaiting_pickup

{
  "event": "shipment.awaiting_pickup",
  "event_label": "Aguardando Retirada",
  "event_timestamp": "2026-07-22T10:15:30-03:00",
  "idempotency_key": "d9428888-122b-11e1-b85c-61cd3cbb3210",
  "cancelable": false,
  "order": {
    "pedido_id": 12345,
    "codigo_transacao": "ABC123",
    "referencia_externa": "pedido-987",
    "plataforma": "Braip",
    "status": {
      "code": 18,
      "label": "Aguardando Retirada"
    },
    "motivo_parado": null,
    "customer": {
      "nome": "João da Silva",
      "cpf": "123.456.789-00",
      "email": "[email protected]",
      "telefone": "(11) 99999-9999",
      "endereco": {
        "logradouro": "Rua Exemplo",
        "numero": "123",
        "complemento": null,
        "bairro": "Centro",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01000-000",
        "pais": "BR"
      }
    },
    "items": [
      {
        "descricao": "Produto Exemplo",
        "quantidade": 1,
        "valor_unitario_cents": 16785,
        "produto": {
          "id": 42,
          "nome": "Produto Exemplo"
        }
      }
    ],
    "frete_cents": 1895
  },
  "shipment": {
    "tracking_code": "AA123456789BR",
    "tracking_url": "https://ev.paylog.cash/rastreio/AA123456789BR",
    "carrier": {
      "code": "correios",
      "name": "CORREIOS"
    },
    "tracking_status": {
      "code": 60,
      "label": "Aguardando Retirada"
    },
    "description": "Objeto aguardando retirada no endereço indicado",
    "location": "São Paulo/SP",
    "occurred_at": "2026-07-22T10:10:00-03:00",
    "collection_address": {
      "unit_type": "Agência dos Correios",
      "logradouro": "Avenida Central",
      "numero": "100",
      "bairro": "Centro",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01000-000",
      "pickup_deadline": "2026-07-29",
      "pickup_list_code": "408161154094"
    },
    "delivery_proof": {
      "image_url": null,
      "signature_url": null,
      "received_by": null,
      "signatory": null,
      "delivery_lat": null,
      "delivery_lng": null
    }
  },
  "meta": {
    "webhook_version": 2,
    "api_version": 2
  }
}

Quando ainda não existe rastreio, o objeto shipment mantém esta forma:

{
  "tracking_code": null,
  "tracking_url": null,
  "carrier": {
    "code": null,
    "name": null
  },
  "tracking_status": {
    "code": null,
    "label": null
  },
  "description": null,
  "location": null,
  "occurred_at": null,
  "collection_address": null,
  "delivery_proof": {
    "image_url": null,
    "signature_url": null,
    "received_by": null,
    "signatory": null,
    "delivery_lat": null,
    "delivery_lng": null
  }
}

#Campo cancelable

cancelable não é inferido pelo nome do evento. Ele é true somente quando o status atual do pedido está nesta lista:

Em qualquer outro status, o valor é false.

#Verificação HMAC-SHA256

O painel gera um segredo de 40 caracteres ao criar o endpoint e o exibe uma única vez. A assinatura é:

sha256=<HMAC-SHA256 hexadecimal do corpo JSON bruto usando o segredo>

#PHP

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

$valid = hash_equals($expected, $received);

#Node.js

const crypto = require('node:crypto');

const received = req.header('X-Webhook-Signature') ?? '';
const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');

const receivedBuffer = Buffer.from(received);
const expectedBuffer = Buffer.from(expected);
const valid = receivedBuffer.length === expectedBuffer.length
  && crypto.timingSafeEqual(receivedBuffer, expectedBuffer);

#Python

import hashlib
import hmac

received = request.headers.get("X-Webhook-Signature", "")
expected = "sha256=" + hmac.new(
    secret.encode(),
    request.get_data(),
    hashlib.sha256,
).hexdigest()

valid = hmac.compare_digest(expected, received)

#Tentativas, logs e pausa automática

Uma resposta não-2xx ou um timeout/erro de conexão falha a tentativa. O job permite quatro tentativas totais:

Cada tentativa cria um registro no histórico com evento, payload, número da tentativa, resultado, status HTTP e até 5.000 caracteres do corpo da resposta. Uma resposta 2xx zera consecutive_failures.

Pausa automática conta falhas terminais, não requisições individuais:

1. Um ciclo de entrega só é terminal depois de esgotar suas até quatro tentativas.
2. Ao terminar sem sucesso, o endpoint recebe uma falha consecutiva.
3. Após três ciclos terminais consecutivos, o endpoint é pausado (is_active = false).
4. Reativar no painel limpa o contador, remove a pausa e ativa o endpoint.

Isso representa até 12 requisições HTTP malsucedidas em três ciclos, se todas as quatro tentativas forem executadas em cada ciclo. Um sucesso entre ciclos reinicia a contagem.

#Teste pelo painel

O teste usa o primeiro evento selecionado no endpoint (ou order.created como fallback), gera o mesmo full-schema com dados sintéticos e assina o corpo com o mesmo algoritmo.

Diferenças do teste:

• envia X-Webhook-Test: true;
• usa timeout de 10 segundos;
• faz uma única chamada direta, sem fila ou reenvio;
• não cria registro no histórico de entregas;
• não altera o contador de falhas nem pausa o endpoint;
• considera qualquer resposta 2xx bem-sucedida.

#Resposta e idempotência

Retorne qualquer status 2xx em até 30 segundos. Respostas 3xx, 4xx, 5xx, timeout e erros de conexão entram na política de tentativas.

Persista idempotency_key e ignore uma chave já processada. Isso torna seguro receber novamente a mesma entrega: as tentativas automáticas do job, o botão Reenviar de uma entrega do histórico e uma repetição da fila reaproveitam o payload original, portanto repetem a mesma idempotency_key.

#Reenvio em lote (por data / produto)

O painel também oferece um reenvio em lote por intervalo de datas e, opcionalmente, por produto. Ele não reenvia entregas antigas: reconstrói o payload a partir do estado atual do pedido. As diferenças abaixo são obrigatórias para quem consome esses eventos.