Webhooks de Rastreio

Quando usar

Cadastre um webhook quando outro sistema da empresa (ERP, fila interna, BI) precisa saber na hora que o rastreio mudou — saiu para entrega, entregue, em devolução.

Quem pode fazer

Só dono ou admin do time criam, testam, desativam e excluem endpoints. Membros veem a tela, mas não gerenciam. Não há gate extra de plano para esta tela.

Pré-requisitos

• Uma URL HTTPS que responda 2xx aos POSTs da plataforma.
• Papel de dono ou admin na empresa.

Passo a passo (painel do time)

1. 1. Abra Webhooks. No menu Integrações & API → Webhooks (selo Novo) você vê os endpoints da empresa. O contrato HTTP desta mesma página continua abaixo, para quem cadastra pela API.

   

2. 2. Crie o endpoint. Clique em Novo webhook. Dê um nome, a URL HTTPS e marque os eventos (em curso, saiu para entrega, aguardando retirada, entregue, entre outros). O evento default recebe qualquer tipo.

   

3. 3. Copie o secret agora. O secret HMAC aparece uma vez. Guarde no cofre da empresa. Cada POST traz o header X-SeuRastreio-Signature. A validação está na seção de autenticação abaixo — não duplicamos o schema aqui.

   

4. 4. Teste e acompanhe as entregas. No card do endpoint, Enviar teste dispara um evento sintético. Ver entregas mostra tentativas, falhas e o último erro. Depois de falhas consecutivas o endpoint pode desligar sozinho: use Reativar. Não cole o secret em ticket.

   

Resultado esperado

Cada mudança do último evento do rastreio gera um POST na sua URL. Falhas entram em retry; o painel mostra o histórico. O contrato da API pública permanece nas seções seguintes.

Erros comuns (painel)

• Sem botão Novo webhook. Você está como membro. Peça a um dono ou admin.
• URL recusada. Use HTTPS. Endpoints que falham demais são desativados.
• Assinatura inválida no seu lado. Siga a seção de validação HMAC abaixo; o secret antigo deixa de valer se você rotacionar pela API.

Relacionados

• Criar chaves de API da empresa
• API de rastreio
• Início rápido

Visão Geral

Webhooks disparam sempre que o último evento de um rastreio mudar, tanto para rastreios avulsos como para pedidos integrados (Loja Integrada, Nuvemshop etc.). Você cadastra endpoints HTTPs e escolhe quais tipos de evento cada endpoint assina.

Um evento pode gerar zero, um ou vários POSTs — um para cada endpoint elegível. As entregas são enfileiradas de forma durável, entregues por workers em background e reentregues com backoff em caso de falha (não bloqueiam o processamento da fila de rastreio).

Autenticação (gerenciamento via API)

Para cadastrar, listar e excluir webhooks via API, use o header Authorization: Bearer sr_live_.... Cada chave pertence a um time e só enxerga os webhooks do próprio time.

Authorization: Bearer sr_live_sua_chave_aqui

Tipos de evento

Ao criar um webhook você informa a lista de eventos assinados. Use default como catch-all para receber qualquer tipo.

Payload entregue

O corpo da requisição é JSON com o evento, informações do time, do rastreio e opcionalmente do pedido vinculado.

{
  "id": "d1e5b8a3-...",
  "event": "saiu_para_entrega",
  "eventLabel": "Saiu para entrega",
  "occurredAt": "2026-04-21T14:32:01.512Z",
  "team": { "id": "team_abc", "slug": "minha-loja" },
  "tracking": {
    "codigo": "AA123456789BR",
    "tipo": "normal",
    "lastEventDescription": "Objeto saiu para entrega ao destinatário",
    "lastEventLocation": "São Paulo/SP",
    "lastEventAt": "2026-04-21T14:30:00.000Z"
  },
  "order": {
    "orderId": "livexa_12345",
    "status": "shipped",
    "operationalStatus": "saiu_para_entrega"
  }
}

O campo order só está presente quando o evento foi disparado por uma atualização de pedido integrado.

Headers enviados

Verificando a assinatura (HMAC-SHA256)

Compute HMAC-SHA256(secret, `$`{timestamp}.{rawBody}$``) e compare com o valor de v1 em X-SeuRastreio-Signature. Use comparação em tempo constante (ex.: crypto.timingSafeEqual no Node).

import crypto from "node:crypto";

export function verifySeuRastreioSignature(
  secret: string,
  rawBody: string,
  signatureHeader: string,
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=") as [string, string]),
  );
  const ts = Number(parts.t);
  const v1 = parts.v1;
  if (!ts || !v1) return false;

  // Rejeita requisições com mais de 5 minutos para mitigar replay.
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Política de retry & auto-disable

Uma resposta HTTP 2xx conta como sucesso. Qualquer outro status, timeout (10s) ou erro de rede agenda nova tentativa com backoff crescente:

Após 10 falhas consecutivas no mesmo endpoint, ele é desativado automaticamente (enabled = false). Reative pela dashboard ou enviando PATCH com enabled: true.

Endpoints REST para gerenciar webhooks

Listar webhooks do time

curl -sS "https://seurastreio.com.br/api/public/webhooks" \
  -H "Authorization: Bearer sr_live_sua_chave"

Criar webhook

curl -sS -X POST "https://seurastreio.com.br/api/public/webhooks" \
  -H "Authorization: Bearer sr_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração ERP",
    "url": "https://meu-erp.com/webhooks/seurastreio",
    "events": ["em_curso","saiu_para_entrega","aguardando_retirada","em_devolucao","devolvido","entregue"]
  }'

A resposta (HTTP 201) inclui o campo secret em claro — guarde agora, pois ele não é exibido em chamadas posteriores.

Consultar webhook

Atualizar webhook

Aceita qualquer combinação de name, url, events e enabled. Enviar {"enabled": true} reativa um endpoint que tenha sido desabilitado automaticamente.

Excluir webhook

Rotacionar o secret

Gera um novo secret e invalida o anterior. A resposta expõe o novo secret em claro.

Disparar um evento de teste

Enfileira um delivery sintético (event=default e _test: true no payload) para validar conectividade e assinatura.

Listar entregas recentes

Query opcional limit (default 50, máx 200). Retorna status, número de tentativas, último erro e nextAttemptAt.

Códigos de status (API de gerenciamento)

atualizadoEm

2026-08-20

superficie

dashboard

owner

Technical Writer

printsGeradosEm

2026-08-20