Skip to main content
Webhooks permitem que sua aplicação receba notificações em tempo real quando ocorrem alterações em pedidos, evitando polling e simplificando a sincronização. No momento, os eventos disponíveis são do módulo de Pedidos: criação e atualização de status. Consulte Eventos notificados para a lista completa e exemplos de payload.

​
Fluxo recomendado

Quando um evento ocorre, a Cardápio Web envia uma requisição POST com Content-Type: application/json para a URL configurada. Sua aplicação precisa validar o token no header X-Webhook-Token e responder com HTTP 200 em até 5 segundos. Para obter o pedido completo, use o order_id do payload em Consultar detalhes do pedido. Sugestão: se o processamento do evento for demorado, considere separar o recebimento da lógica de integração:
  1. Valide o token e verifique o event_id para ignorar duplicatas.
  2. Persista o payload em uma fila ou banco de dados.
  3. Responda com HTTP 200.
  4. Processe o restante de forma assíncrona (consulta de detalhes, gravação no banco, regras de negócio).
Recomendamos processar webhooks de forma assíncrona quando possível. Assim, o endpoint responde rápido enquanto o trabalho mais pesado roda em segundo plano. Isso ajuda a manter um tempo de resposta consistente e reduz o risco de retentativas por timeout.

​
Dois modelos de configuração

Configure webhook_url no cadastro do app. Quando um estabelecimento instala o app, a Cardápio Web cria ou atualiza automaticamente o webhook da instalação.Autenticação
  • O webhook_token é gerado automaticamente após o cadastro do app e enviado pelo time de suporte junto com o client_id
  • Cada notificação inclui o token no header X-Webhook-Token
Entrega e ciclo de vida
  • A entrega começa após a instalação ativa do estabelecimento
  • A desinstalação interrompe a entrega de webhooks daquela instalação
  • Se o webhook for pausado após falhas consecutivas, entre em contato com integracao@cardapioweb.com para reativá-lo
Webhooks de apps do marketplace não devem ser editados manualmente no Portal. A configuração vem do app.
Para testar no Sandbox, cadastre o app no ambiente de Sandbox, instale-o no seu estabelecimento de teste e realize pedidos para validar a entrega na webhook_url.

​
Retornando HTTP 200

Para que a Cardápio Web considere a notificação processada com sucesso, a resposta deve ter status HTTP 200 OK. Qualquer outro status é tratado como falha. O tempo limite para a resposta é de 5 segundos. Timeouts também são tratados como falha e disparam retentativas. Se o processamento completo do pedido puder ultrapassar esse limite, considere enfileirar o evento e retornar 200 OK antes de consultar a API ou aplicar regras de negócio. Operações lentas no handler aumentam o risco de timeout e podem levar o webhook à pausa após falhas consecutivas. Em caso de falha na entrega, a Cardápio Web pode reenviar o mesmo evento até 15 vezes. Se optar por processamento assíncrono, vale usar o event_id como chave de idempotência para ignorar duplicatas.

​
Retentativas

Em caso de falha (status diferente de 200 ou timeout), a Cardápio Web tenta novamente até receber HTTP 200 OK ou atingir o limite de 15 retentativas. Após esgotar as retentativas, a Cardápio Web descarta a notificação e pausa o webhook. Enquanto pausado, novas notificações também são descartadas (não ficam enfileiradas). Reativação
  • Integração legada: reative manualmente no Portal (Configurações → Integrações → API) após corrigir o endpoint
  • CW App Store: entre em contato com integracao@cardapioweb.com após corrigir a webhook_url ou o endpoint de recebimento

​
Como testar

A Cardápio Web envia webhooks para uma URL HTTPS pública. Durante o desenvolvimento, escolha a abordagem que melhor se encaixa no seu ambiente:
Use o ngrok para expor um servidor rodando na sua máquina e receber notificações reais no seu código.
  1. Suba um servidor HTTP local que trate requisições POST (por exemplo, na porta 3000).
  2. Exponha a porta com o ngrok:
  1. Copie a URL HTTPS gerada (ex.: https://abc123.ngrok-free.app) e cadastre-a como webhook_url no cadastro do app ou no Portal (integração legada).
  2. Realize um pedido de teste no Sandbox e verifique se a notificação chegou ao seu servidor.
No plano gratuito do ngrok, a URL muda a cada sessão. Atualize a webhook_url sempre que reiniciar o túnel.
Consulte Eventos notificados para a estrutura dos payloads.
Última modificação em 30 de junho de 2026