Eventos de webhook
Todos os avisos que a OTL envia, a permissão que cada um exige e um exemplo do corpo.
Cada evento exige a permissão que leria o mesmo dado pela API: a integração só pode assinar o que as permissões dela alcançam. O campo dados tem o mesmo formato das respostas da API.
Lista
| Evento | Permissão | Quando |
|---|---|---|
pedido.criado | pedidos:ler | Um pedido foi fechado — pelo painel ou por uma integração. |
pedido.status_alterado | pedidos:ler | A OTL mudou o status do pedido (pago, em separação, enviado, entregue, cancelado, estornado). |
pedido.rastreio_adicionado | pedidos:ler | Um código de rastreio novo entrou no pedido. |
pedido.comprovante_validado | pedidos:ler | A OTL conferiu o comprovante de pagamento. |
etiqueta.emitida | etiquetas:ler | Uma etiqueta de envio foi emitida e paga — pelo painel ou por uma integração. |
etiqueta.status_alterado | etiquetas:ler | A etiqueta foi impressa ou despachada pela OTL, ou cancelada. |
financeiro.lancamento_criado | financeiro:ler | Um crédito ou débito entrou no saldo do parceiro. |
produto.estoque_atualizado | produtos:ler | O estoque de alguma numeração do produto mudou. |
produto.preco_atualizado | produtos:ler | O preço de atacado ou o preço sugerido do produto mudou. alterados diz qual. |
produto.nome_alterado | produtos:ler | O título do produto mudou. |
produto.categorias_alteradas | produtos:ler | As categorias, os estilos ou as tags do produto mudaram. |
produto.criado | produtos:ler | Um produto novo entrou no catálogo. |
produto.desativado | produtos:ler | Um produto saiu do catálogo. |
produto.reativado | produtos:ler | Um produto que estava fora do catálogo voltou. |
produto.lote | produtos:ler | Vários produtos mudaram de uma vez (carga de estoque, atualização em massa): em vez de um aviso por mudança, chega um só, com a lista em itens. Não é assinado — vem no lugar dos eventos de produto que o endereço assina. |
cliente.criado | clientes:ler | Um cliente entrou na agenda do parceiro — pelo painel, pela API ou salvo ao fechar um pedido. |
cliente.atualizado | clientes:ler | Os dados de um cliente da agenda mudaram. alterados diz quais campos. |
cliente.removido | clientes:ler | Um cliente saiu da agenda do parceiro. |
teste.ping | — | Enviado pelo botão "Enviar teste" do painel. Não precisa ser assinado. |
Produtos
O campo dados.produto é o produto inteiro, como em Detalhar produto — inclusive o precoAtual da loja do parceiro e o estoque de todas as numerações. Alguns eventos trazem ainda alterados (o que mudou) e anterior (o valor de antes).
produto.lote
, com a lista em dados.itens. Cada item traz o evento e os mesmos campos que
o aviso avulso teria. Trate os dois formatos — quem ignora o lote perde justamente as cargas.
precoAtual)
não disparam aviso. Regravar um valor igual ao que já estava também não.
produto.estoque_atualizado
O estoque de alguma numeração do produto mudou.
{
"id": "evt_cmh2x9k080001",
"evento": "produto.estoque_atualizado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
}
}produto.preco_atualizado
O preço de atacado ou o preço sugerido do produto mudou. alterados diz qual.
{
"id": "evt_cmh2x9k090001",
"evento": "produto.preco_atualizado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
},
"alterados": [
"precoAtacado"
],
"anterior": {
"precoAtacado": "129.90",
"precoSugerido": "259.90"
}
}
}produto.nome_alterado
O título do produto mudou.
{
"id": "evt_cmh2x9k100001",
"evento": "produto.nome_alterado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
},
"anterior": {
"titulo": "Tênis Adidas Forum Branco"
}
}
}produto.categorias_alteradas
As categorias, os estilos ou as tags do produto mudaram.
{
"id": "evt_cmh2x9k110001",
"evento": "produto.categorias_alteradas",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
},
"alterados": [
"categorias"
]
}
}produto.criado
Um produto novo entrou no catálogo.
{
"id": "evt_cmh2x9k120001",
"evento": "produto.criado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
}
}produto.desativado
Um produto saiu do catálogo.
{
"id": "evt_cmh2x9k130001",
"evento": "produto.desativado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": false,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
}
}produto.reativado
Um produto que estava fora do catálogo voltou.
{
"id": "evt_cmh2x9k140001",
"evento": "produto.reativado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
}
}produto.lote
Vários produtos mudaram de uma vez (carga de estoque, atualização em massa): em vez de um aviso por mudança, chega um só, com a lista em itens. Não é assinado — vem no lugar dos eventos de produto que o endereço assina.
{
"id": "evt_cmh2x9k150001",
"evento": "produto.lote",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"total": 2,
"itens": [
{
"evento": "produto.estoque_atualizado",
"produto": {
"sku": "320",
"titulo": "Tênis Adidas Forum Low Branco",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
"precoAtacado": "139.90",
"precoSugerido": "259.90",
"precoAtual": "209.90",
"numeracoes": [
{
"numeracao": "38",
"skuVariacao": "320U",
"estoque": 4
},
{
"numeracao": "39",
"skuVariacao": "320V",
"estoque": 0
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
},
{
"evento": "produto.preco_atualizado",
"produto": {
"sku": "411",
"titulo": "Tênis Nike Court Vision Preto",
"imagem": "https://cdn.otlshoes.com.br/otl-catalog/411.webp",
"precoAtacado": "109.90",
"precoSugerido": "199.90",
"precoAtual": "169.90",
"numeracoes": [
{
"numeracao": "40",
"skuVariacao": "411W",
"estoque": 2
}
],
"categorias": [
{
"id": "cmf1c0a2b0001",
"nome": "Casual"
}
],
"estilos": [
{
"id": "cmf1e0a2b0001",
"nome": "Masculino"
}
],
"tags": [
{
"id": "cmf1t0a2b0001",
"nome": "Lançamento"
}
],
"ativo": true,
"atualizadoEm": "2026-09-29T14:03:00-03:00"
},
"alterados": [
"precoAtacado"
],
"anterior": {
"precoAtacado": "99.90",
"precoSugerido": "199.90"
}
}
]
}
}Pedidos
O campo dados.pedido é o resumo do pedido. Para itens, destinatário, rastreios e anexos, busque Detalhar pedido com o id. Os eventos valem para pedidos feitos no painel e pela API — o campo origem diz qual.
pedido.criado
Um pedido foi fechado — pelo painel ou por uma integração.
{
"id": "evt_cmh2x9k010001",
"evento": "pedido.criado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"pedido": {
"id": "cmg8k1p2a0007",
"numero": 12,
"status": "AGUARDANDO_PAGAMENTO",
"total": "279.80",
"origem": "API",
"referenciaExterna": "PED-778",
"enviarPara": "CLIENTE",
"criadoEm": "2026-09-20T09:15:00-03:00",
"atualizadoEm": "2026-09-20T09:15:00-03:00"
}
}
}pedido.status_alterado
A OTL mudou o status do pedido (pago, em separação, enviado, entregue, cancelado, estornado).
{
"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"
}
}
}pedido.rastreio_adicionado
Um código de rastreio novo entrou no pedido.
{
"id": "evt_cmh2x9k030001",
"evento": "pedido.rastreio_adicionado",
"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"
},
"rastreio": {
"id": "cmg8n9q4t0001",
"codigo": "AA123456789BR",
"transportadora": "Correios",
"validado": false,
"cadastradoPeloParceiro": false,
"criadoEm": "2026-09-22T14:03:00-03:00"
}
}
}pedido.comprovante_validado
A OTL conferiu o comprovante de pagamento.
{
"id": "evt_cmh2x9k040001",
"evento": "pedido.comprovante_validado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"pedido": {
"id": "cmg8k1p2a0007",
"numero": 12,
"status": "AGUARDANDO_PAGAMENTO",
"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"
},
"anexo": {
"id": "cmg8k5z7u0004",
"tipo": "COMPROVANTE",
"nomeArquivo": "comprovante-pix.pdf",
"tipoArquivo": "application/pdf",
"tamanhoBytes": 51234,
"validado": true,
"enviadoPeloParceiro": true,
"criadoEm": "2026-09-20T09:20:00-03:00"
}
}
}Etiquetas
O campo dados.etiqueta é a etiqueta como em Etiquetas do pedido, com o pedido a que ela pertence. Em etiqueta.status_alterado vem também o statusAnterior. Os eventos valem para etiquetas emitidas pelo painel e pela API.
etiqueta.emitida
Uma etiqueta de envio foi emitida e paga — pelo painel ou por uma integração.
{
"id": "evt_cmh2x9k050001",
"evento": "etiqueta.emitida",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"etiqueta": {
"id": "cmg8p2r5v0003",
"pedido": {
"id": "cmg8k1p2a0007",
"numero": 12
},
"servico": {
"id": 1,
"nome": "PAC"
},
"transportadora": "Correios",
"valor": "23.72",
"status": "GERADA",
"rastreio": "AA123456789BR",
"emitidaEm": "2026-09-21T11:00:00-03:00",
"impressaEm": null,
"despachadaEm": null,
"canceladaEm": null,
"atualizadoEm": "2026-09-21T11:00:00-03:00"
}
}
}etiqueta.status_alterado
A etiqueta foi impressa ou despachada pela OTL, ou cancelada.
{
"id": "evt_cmh2x9k060001",
"evento": "etiqueta.status_alterado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"etiqueta": {
"id": "cmg8p2r5v0003",
"pedido": {
"id": "cmg8k1p2a0007",
"numero": 12
},
"servico": {
"id": 1,
"nome": "PAC"
},
"transportadora": "Correios",
"valor": "23.72",
"status": "DESPACHADA",
"rastreio": "AA123456789BR",
"emitidaEm": "2026-09-21T11:00:00-03:00",
"impressaEm": "2026-09-22T09:00:00-03:00",
"despachadaEm": "2026-09-22T14:03:00-03:00",
"canceladaEm": null,
"atualizadoEm": "2026-09-22T14:03:00-03:00",
"statusAnterior": "IMPRESSA"
}
}
}Clientes
O campo dados.cliente é o resumo do cliente: id, nome e as datas. O contato e o endereço não vão no aviso — são dados pessoais do seu cliente, e o corpo de um webhook costuma ficar guardado nos registros da automação que o recebe. Para o cadastro completo, busque Detalhar cliente com o id.
Em cliente.atualizado, alterados traz o nome dos campos que mudaram (nome, whatsapp, endereco.cep…), nunca os valores. Os eventos valem para a agenda inteira: clientes cadastrados no painel, pela API ou salvos ao fechar um pedido.
GET /v1/clientes/{id} responde 404. Os pedidos
já feitos para ele continuam com o endereço que tinham.
cliente.criado
Um cliente entrou na agenda do parceiro — pelo painel, pela API ou salvo ao fechar um pedido.
{
"id": "evt_cmh2x9k160001",
"evento": "cliente.criado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"cliente": {
"id": "cmg7c3d4e0002",
"nome": "Maria Oliveira",
"criadoEm": "2026-09-18T11:00:00-03:00",
"atualizadoEm": "2026-09-18T11:00:00-03:00"
}
}
}cliente.atualizado
Os dados de um cliente da agenda mudaram. alterados diz quais campos.
{
"id": "evt_cmh2x9k170001",
"evento": "cliente.atualizado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"cliente": {
"id": "cmg7c3d4e0002",
"nome": "Maria Oliveira",
"criadoEm": "2026-09-18T11:00:00-03:00",
"atualizadoEm": "2026-09-29T14:03:00-03:00"
},
"alterados": [
"whatsapp",
"endereco.cep",
"endereco.rua"
]
}
}cliente.removido
Um cliente saiu da agenda do parceiro.
{
"id": "evt_cmh2x9k180001",
"evento": "cliente.removido",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"cliente": {
"id": "cmg7c3d4e0002",
"nome": "Maria Oliveira",
"criadoEm": "2026-09-18T11:00:00-03:00",
"atualizadoEm": "2026-09-29T14:03:00-03:00"
}
}
}Financeiro
financeiro.lancamento_criado
Um crédito ou débito entrou no saldo do parceiro.
{
"id": "evt_cmh2x9k070001",
"evento": "financeiro.lancamento_criado",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"lancamento": {
"id": "cmg9a2b3c0001",
"tipo": "CREDITO",
"valor": "139.90",
"descricao": "Devolução do pedido #12",
"pedido": {
"id": "cmg8k1p2a0007",
"numero": 12
},
"criadoEm": "2026-09-25T09:00:00-03:00"
}
}
}Teste
teste.ping
Enviado pelo botão "Enviar teste" do painel. Não precisa ser assinado.
{
"id": "evt_cmh2x9k190001",
"evento": "teste.ping",
"criadoEm": "2026-09-29T14:03:00-03:00",
"ambiente": "producao",
"integracao": {
"id": "cmg1a2b3c0009",
"nome": "n8n – automações"
},
"dados": {
"mensagem": "Teste enviado pelo painel. Se você recebeu isto, o endereço está funcionando."
}
}