Webhooks

Em vez de o seu sistema perguntar toda hora, a OTL avisa um endereço seu quando algo muda.

A API responde quando perguntam. O webhook avisa quando acontece: o estoque de um produto mudou, o preço subiu, um pedido foi pago, um rastreio entrou. É o que liga a OTL a uma automação (n8n, Make, Zapier) ou ao seu ERP sem ficar consultando de minuto em minuto.

Como começar

1. A OTL libera os webhooks para a conta do parceiro. É uma liberação à parte da API — peça à equipe OTL.
2. O parceiro cadastra o endereço no painel: em Integrações, no card da integração, botão Webhooks. Ele informa a URL, escolhe os eventos e recebe o segredo de assinatura — que aparece uma única vez.
3. O seu sistema recebe um POST em JSON a cada evento, confere a assinatura e responde 2xx.

O que chega no seu endereço

Um POST com estes cabeçalhos:

E este corpo:

{
  "id": "evt_cmh2x9k020001",
  "evento": "pedido.status_alterado",
  "criadoEm": "2026-09-29T14:03:00-03:00",
  "ambiente": "producao",
  "integracao": {
    "id": "cmg1a2b3c0009",
    "nome": "n8n – automações"
  },
  "dados": {
    "pedido": {
      "id": "cmg8k1p2a0007",
      "numero": 12,
      "status": "ENVIADO",
      "total": "279.80",
      "origem": "API",
      "referenciaExterna": "PED-778",
      "enviarPara": "CLIENTE",
      "criadoEm": "2026-09-20T09:15:00-03:00",
      "atualizadoEm": "2026-09-22T14:03:00-03:00",
      "statusAnterior": "EM_SEPARACAO"
    }
  }
}

O corpo é enxuto de propósito: o aviso de pedido leva o resumo (número, status, total, referência), sem itens nem endereço do cliente. Para o detalhe, busque o pedido pela API com o id.

O que o seu endereço precisa fazer

• Responder 2xx em até 10 segundos. Qualquer outra resposta — inclusive redirecionamento (3xx), que não é seguido — conta como falha.
• Responder primeiro, processar depois. Guarde o evento numa fila sua e devolva 200 na hora. Se o processamento demorar mais que 10 segundos, a OTL entende que falhou e manda de novo.
• Conferir a assinatura antes de confiar no conteúdo.
• Ignorar evento repetido. A entrega é “pelo menos uma vez”: o mesmo evento pode chegar duas vezes. Guarde o X-OTL-Evento-Id dos que já processou.
• Não depender da ordem. Uma nova tentativa de um evento antigo pode chegar depois de um evento mais novo. Os eventos trazem o estado atual completo (o status do pedido, o estoque de todas as numerações) e o criadoEm: aplique o mais recente e descarte o mais velho.
• Ignorar o que não conhece. Campos e tipos de evento novos entram sem aviso.

Quando a entrega falha

A OTL tenta de novo, com espera crescente:

Depois da 8ª tentativa a entrega fica como falhou. O parceiro vê cada entrega no painel, em Webhooks → Histórico, com o erro, e pode reenviar.

Eventos de produto: de quais produtos

Um catálogo grande gera muitos avisos. Cada endereço escolhe de quais produtos quer ouvir:

• Só o que a loja do parceiro vende — segue a seleção da loja dele no HUB, ao vivo. É o padrão de quem tem loja.
• Só uma lista de SKUs, informada por ele.
• Todo o catálogo.

Os avisos de estoque são agrupados: várias mudanças do mesmo produto em 1 minuto chegam como um evento, com o estoque final.

Mudança em massa: produto.lote

Uma carga de estoque mexe em dezenas de produtos de uma vez. Em vez de uma chamada por mudança, o seu endereço recebe uma só, com o evento produto.lote:

{
  "evento": "produto.lote",
  "dados": {
    "total": 2,
    "itens": [
      { "evento": "produto.estoque_atualizado", "produto": { "sku": "320", "...": "..." } },
      { "evento": "produto.preco_atualizado", "produto": { "sku": "411", "...": "..." },
        "alterados": ["precoAtacado"], "anterior": { "precoAtacado": "99.90", "precoSugerido": "199.90" } }
    ]
  }
}

• Cada item é um aviso de produto: o campo evento diz qual, e o resto é igual ao dados que ele teria sozinho. Percorra itens e trate cada um com o código que você já tem.
• Só entra o que o endereço assina e os produtos do filtro dele. O mesmo produto pode aparecer mais de uma vez, com eventos diferentes (preço e estoque, por exemplo).
• Você não assina o produto.lote: ele vem no lugar dos eventos de produto que o endereço já assina. Se só uma mudança da carga interessa ao seu endereço, ela chega como o evento avulso.
• Até 100 itens por lote. Uma carga maior chega em mais de uma chamada.
• O cabeçalho X-OTL-Evento vem como produto.lote: se a sua automação separa pelo cabeçalho, inclua esse valor.

O exemplo completo está em Eventos.

O webhook não substitui a sincronização

Em três situações a OTL não acumula eventos para entregar depois:

• a API do parceiro está suspensa, ou os webhooks não estão liberados;
• o prazo para aceitar uma versão nova dos Termos da API terminou sem o aceite;
• o token da integração venceu ou a integração foi revogada;
• o endereço está desligado.

Ao voltar, não há reenvio do período: ressincronize com atualizadoDesde.

Testar

• Enviar teste, no painel, manda um evento teste.ping na hora e mostra o que o seu endereço respondeu.
• Para ver o corpo e os cabeçalhos crus antes de programar, aponte o webhook para um serviço de inspeção, como o webhook.site.
• No sandbox os webhooks funcionam sem liberação e aceitam http://. Eles são cadastrados no painel oficial, em Integrações → Ambiente de testes → Webhooks do token de teste, e recebem o que acontece na conta de teste: um pedido ou um cliente criado com o token otl_sbx_… dispara o aviso de verdade. Os eventos de produto chegam quando o catálogo real muda — o ambiente de testes é atualizado a cada poucos minutos.
• Os eventos que dependem da equipe OTL (status do pedido, comprovante validado, lançamento no saldo) são disparados pelos simuladores.

Regras do endereço

• https:// obrigatório em produção, na porta padrão (443).
• Precisa ser um endereço público: localhost, IPs de rede interna e nomes sem domínio são recusados.
• Sem usuário e senha na URL. Para proteger o endereço, confira a assinatura.