Webhooks & Eventos de Rastreio - BulkRoute Central de Ajuda

Em vez de realizar consultas repetitivas (polling) para saber se um pedido foi entregue, configure um Webhook no BulkRoute para receber chamadas POST automáticas em tempo real.

Como funciona

Carrier atualiza status → BulkRoute normaliza → Dispara webhook outbound → Seu sistema recebe POST

O webhook é disparado assincronamente via BullMQ com retry automático (5 tentativas com backoff exponencial).

1. Configurando seu Endpoint de Webhook

No painel, vá em Configurações > Webhooks.
Informe a URL do seu servidor que receberá os eventos (ex: https://meusistema.com.br/api/webhooks/bulkroute).
Copie o Webhook Secret gerado (usado para validar a assinatura de segurança).
Selecione os eventos que deseja receber (ou “Todos”).
Salve.

Requisitos do seu endpoint

Deve aceitar POST com body JSON
Deve retornar 200 OK em até 10 segundos (senão o BulkRoute considera timeout e faz retry)
Deve ser acessível publicamente (não localhost)
Deve validar a assinatura HMAC (ver abaixo)
Deve ser idempotente (pode receber o mesmo evento mais de uma vez em caso de retry)

2. Eventos disponíveis

Evento	Descrição	Quando dispara
`shipment.created`	Envio criado	Quando um shipment é criado (manual ou via API)
`shipment.status_updated`	Status alterado	Sempre que o status muda (PICKED_UP, IN_TRANSIT, etc.)
`shipment.delivered`	Entrega concluída	Quando o status muda para DELIVERED
`shipment.exception`	Ocorrência registrada	Quando o status muda para FAILED
`shipment.cancelled`	Envio cancelado	Quando um shipment é cancelado
`label.generated`	Etiqueta gerada	Quando uma etiqueta é gerada com sucesso
`quote.completed`	Cotação finalizada	Quando uma cotação retorna resultados
`bid.created`	Bid criado	Quando um freight bid é criado (manual ou automático)
`bid.acceptance_received`	Carrier propôs preço	Quando um carrier responde a um bid
`bid.accepted`	Bid aceito	Quando o admin escolhe o vencedor do bid

3. Exemplo de Payload Recebido

shipment.status_updated

{
  "event": "shipment.status_updated",
  "timestamp": "2026-09-06T18:30:00Z",
  "data": {
    "shipmentId": "shp_987654321",
    "trackingCode": "BR123456789BR",
    "carrierCode": "braspress",
    "previousStatus": "IN_TRANSIT",
    "currentStatus": "DELIVERED",
    "eventDescription": "Entrega realizada com sucesso",
    "city": "São Paulo",
    "state": "SP",
    "occurredAt": "2026-09-06T18:28:45Z"
  }
}

shipment.created

{
  "event": "shipment.created",
  "timestamp": "2026-09-06T15:00:00Z",
  "data": {
    "shipmentId": "shp_987654321",
    "trackingCode": "BR123456789BR",
    "carrierCode": "braspress",
    "orderId": "PED-12345",
    "recipient": {
      "name": "João Silva",
      "city": "São Paulo",
      "state": "SP"
    }
  }
}

bid.acceptance_received

{
  "event": "bid.acceptance_received",
  "timestamp": "2026-09-06T16:30:00Z",
  "data": {
    "bidId": "bid_123",
    "carrierCode": "CORREIOS",
    "proposedPrice": 45.90,
    "proposedDeadline": 3
  }
}

4. Validação de Assinatura (Segurança HMAC)

Cada requisição enviada pelo BulkRoute inclui o cabeçalho:

X-BulkRoute-Signature: sha256=<hash_calculado>

Para garantir que o webhook veio legitimamente do BulkRoute, valide o hash HMAC-SHA256 utilizando o seu segredo cadastrado:

Node.js

import crypto from 'crypto';

function verifySignature(payloadRaw, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payloadRaw).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signatureHeader));
}

// Express middleware
app.post('/webhooks/bulkroute', (req, res) => {
  const signature = req.headers['x-bulkroute-signature'];
  const rawBody = req.rawBody; // use raw body, not parsed JSON

  if (!verifySignature(rawBody, signature, process.env.BULKROUTE_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  // Process event...
  res.status(200).send('OK');
});

Python (Flask)

import hmac
import hashlib

def verify_signature(payload_raw, signature_header, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload_raw,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

@app.route('/webhooks/bulkroute', methods=['POST'])
def webhook():
    signature = request.headers.get('X-BulkRoute-Signature', '')
    if not verify_signature(request.get_data(), signature, os.environ['BULKROUTE_WEBHOOK_SECRET']):
        return 'Invalid signature', 401

    event = request.json
    # Process event...
    return 'OK', 200

Use o raw body (bytes brutos) para calcular o HMAC — não o body parseado como JSON. Se você usar req.body (já parseado), o hash não vai bater porque a serialização pode mudar a ordem das chaves.

5. Retry e Dead Letter Queue

O BulkRoute tenta entregar cada webhook até 5 vezes:

Tentativa	Delay
1ª	Imediata
2ª	30 segundos
3ª	2 minutos
4ª	10 minutos
5ª	1 hora

Se todas as 5 tentativas falharem, o evento vai para a Dead Letter Queue (DLQ) e fica visível no painel em Configurações > Webhooks > DLQ. Você pode:

Reprocessar um evento da DLQ manualmente
Baixar o payload para debug
Descartar eventos irrelevantes

6. Logs de Webhook

Cada disparo de webhook é logado no painel:

Campo	Descrição
Evento	Tipo do evento (ex: `shipment.status_updated`)
URL	Endpoint que recebeu (ou tentou receber)
Status HTTP	Resposta do seu servidor (200, 500, timeout)
Tentativa	Número da tentativa (1-5)
Latência	Tempo de resposta em ms
Payload	Body enviado (JSON)
Resposta	Body recebido (se houver)

7. Testando seu Webhook

Com ngrok (desenvolvimento local)

# Exponha seu servidor local
ngrok http 3000

# Configure a URL do ngrok no painel do BulkRoute
# https://abc123.ngrok.io/webhooks/bulkroute

Com webhook.site (teste rápido)

Acesse webhook.site
Copie a URL gerada
Configure no painel do BulkRoute
Crie um shipment e observe os eventos chegando em tempo real

Troubleshooting

Problema	Causa	Solução
`401 Unauthorized` no seu servidor	Assinatura inválida	Verificar Webhook Secret
Timeout (10s)	Seu servidor demora	Otimizar processamento ou usar fila
Eventos duplicados	Retry após timeout	Garantir idempotência no seu endpoint
Eventos não chegam	URL incorreta ou offline	Verificar URL e status do servidor
DLQ cheia	Servidor fora do ar	Reprocessar DLQ após restaurar servidor

​Como funciona

​1. Configurando seu Endpoint de Webhook

​Requisitos do seu endpoint

​2. Eventos disponíveis

​3. Exemplo de Payload Recebido

​shipment.status_updated

​shipment.created

​bid.acceptance_received

​4. Validação de Assinatura (Segurança HMAC)

​Node.js

​Python (Flask)

​5. Retry e Dead Letter Queue

​6. Logs de Webhook

​7. Testando seu Webhook

​Com ngrok (desenvolvimento local)

​Com webhook.site (teste rápido)

​Troubleshooting

Como funciona

1. Configurando seu Endpoint de Webhook

Requisitos do seu endpoint

2. Eventos disponíveis

3. Exemplo de Payload Recebido

shipment.status_updated

shipment.created

bid.acceptance_received

4. Validação de Assinatura (Segurança HMAC)

Node.js

Python (Flask)

5. Retry e Dead Letter Queue

6. Logs de Webhook

7. Testando seu Webhook

Com ngrok (desenvolvimento local)

Com webhook.site (teste rápido)

Troubleshooting