Webhook do Cardápio Digital

Quer que o seu sistema saiba na hora que um cliente entrou na loja, que uma mesa pediu a conta ou que um cupom foi usado? O Webhook do Cardápio Digital avisa o seu sistema a cada evento da loja, dos endereços do cliente, das mesas, das comandas, dos cupons e do cashback.

Os avisos do Cardápio Digital chegam no mesmo endereço do Webhook do PDV, que é o único campo a preencher.

Onde ligar

Webhook do PDV (recebe os eventos de pedidos, pagamentos, caixa e estoque): o endereço que recebe também os eventos do Cardápio Digital. Em branco, nada é enviado. Ao salvar, a tela avisa "Webhook do PDV salvo." e lista os eventos enviados.

O endereço precisa começar com http:// ou https://, sem espaços, e não pode apontar para a rede interna. Ele recebe POST com corpo em JSON.

O campo que separa um aviso do outro

Tudo chega no mesmo endereço, e é o acao que diz o que aconteceu no Cardápio Digital:

Todo aviso do Webhook do Cardápio Digital traz também:

companyId — a empresa.

origem — de onde veio o evento, como painel (alguém na tela) ou cardapio (a loja). Nos endereços, também api (a integração) e planilha (a importação de endereços).

enviadoEm — a hora em que o aviso foi enviado.

backendURL — o endereço do backend da sua instalação.

Exemplo de payload de Cupom

O aviso de um cupom que teve o desconto mudado para 15%:

{
  "acao": "cupom-alterado",
  "companyId": 8,
  "cupom": {
    "id": 5,
    "codigo": "BEMVINDO10",
    "tipo": "codigo",
    "descricao": "Desconto da semana",
    "descontoTipo": "percentual",
    "descontoValor": 1500,
    "descontoMaximo": null,
    "pedidoMinimo": null,
    "validoDe": null,
    "validoAte": null,
    "limiteDeUsos": null,
    "usosPorCliente": 1,
    "pedidosParaFidelidade": 5,
    "diasDoAniversario": 7,
    "ativo": true,
    "usos": 0
  },
  "origem": "painel",
  "enviadoEm": "2026-11-07T12:29:37.928Z",
  "backendURL": "https://backend_url.com.br"
}

O mesmo cupom, quando é removido, chega só com o id e o codigo:

{
  "acao": "cupom-removido",
  "companyId": 8,
  "cupom": { "id": 5, "codigo": "BEMVINDO10" },
  "origem": "painel",
  "enviadoEm": "2026-11-07T12:29:46.113Z",
  "backendURL": "https://backend_url.com.br"
}

O que cada aviso traz a mais

Loja (cardapio-alterado): cardapio, com a configuração da loja como está na tela: o slug e o link da loja, ativo (se ela está no ar), os dados do topo, a entrega e a retirada, os horarios, os horariosDaMesa, os diasFechados, pedidoOnline (pedido pela sacola ou pelo WhatsApp), o pagamento online, o cashback e o exemploDaObservacao. O código do front não vai no aviso; frontProprio diz se a loja usa um front próprio.

Cliente que entrou (cardapio-cliente-entrou): cliente, com contactId, numero e nome.

Endereço (cardapio-endereco-salvo e cardapio-endereco-removido): endereco, com id, contactId, apelido, endereco, bairro, cep (com o traço, como 80010-000), principal e usadoEm. O salvo traz também novo: true no endereço cadastrado agora, inclusive o que o pedido com entrega guardou sozinho, sem apelido, e false no alterado. O removido não traz novo.

Mesa (mesa-criada, mesa-alterada e mesa-removida): mesa, com id, nome, ativa, ordem, o link do QR Code e a comanda aberta.

Comanda (comanda-aberta, comanda-conta-pedida e comanda-fechada): comanda, com a mesa, a situacao, o total, o pago e o saldo em centavos, e os pedidos.

Cupom (cupom-criado e cupom-alterado): cupom, com id, codigo, tipo (codigo, boas-vindas, aniversario ou fidelidade), descricao, descontoTipo, descontoValor (em centavos, ou o percentual × 100, como 1500 para 15%), as regras (descontoMaximo, pedidoMinimo, validoDe, validoAte, limiteDeUsos, usosPorCliente, pedidosParaFidelidade e diasDoAniversario), ativo e os usos. Ligar ou desligar o cupom chega como cupom-alterado, com o ativo novo.

Cupom removido (cupom-removido): cupom, só com o id e o codigo.

Cupom usado (cupom-usado): cupom, com as regras e os usos já somados, e uso, com id, contactId, pedidoId, numero, desconto em centavos e, no cupom de aniversário, o ano.

Cashback (cashback-creditado, cashback-usado, cashback-estornado e cashback-expirado): cashback, com contactId, pedidoId, valor e saldo em centavos. O creditado e o usado trazem também o numero do pedido. No cashback-estornado, o tipo é estorno (o saldo que o pedido cancelado tinha usado volta ao cliente) ou anulado (o crédito do pedido entregue que foi cancelado é retirado, com o valor negativo). Nos outros avisos de cashback, o valor vem positivo, também no uso.

Os pedidos da loja e da mesa

Os pedidos do Cardápio Digital chegam pelos avisos de pedido do Webhook do PDV, como pedido-criado, com estes campos a mais:

Pedido pela loja: origem com o valor cardapio.

Pedido na mesa: mesa e comandaId.

Pedido com cupom: no pedido-confirmado, cupom, com id e codigo, e o valor em desconto.

Pedido com cashback: no pedido-confirmado, cashbackUsado, já dentro do desconto.

Os valores do pedido vêm em reais, como 28.9; os do cupom e do cashback, em centavos.

Conta da mesa paga online: link-de-pagamento-gerado com origem cardapio e, quando o pagamento é confirmado, um pagamento-confirmado para cada pedido da comanda, com comandaId no pagamento.

Como saber que o aviso veio daqui

Todo aviso do Webhook do Cardápio Digital traz o cabeçalho X-Pdv-Evento, com o evento, e vai assinado com o Token da Empresa no cabeçalho X-Assinatura-Pdv. O token não vai no corpo do aviso.