Webhooks

Webhooks permitem que sistemas externos recebam notificações automáticas quando eventos acontecem no MeuCardapio.ai. Em vez de consultar a API repetidamente para verificar mudanças, o sistema envia uma requisição HTTP (POST) para a URL configurada sempre que um evento ocorre.

O que são webhooks?

Um webhook funciona como um "aviso automático". Quando algo acontece no seu estabelecimento (um novo pedido, uma mudança de status, um pagamento confirmado), o MeuCardapio.ai envia os dados desse evento para a URL que você configurou. Isso permite:

Integrar com sistemas próprios (ERP, CRM, BI)
Automatizar fluxos de trabalho (ex: notificar equipe no Slack quando chega pedido)
Sincronizar dados com outras plataformas em tempo real
Criar dashboards personalizados com dados atualizados

Casos de uso

Cenário	Descrição
Integração com ERP	Envie pedidos automáticamente para o sistema de gestão da empresa
Notificações personalizadas	Dispare alertas no Slack, Discord ou Telegram quando um pedido chegar
Painel de BI	Alimente dashboards com dados de vendas em tempo real
Automação de marketing	Dispare campanhas quando um pedido for entregue
Controle de estoque	Atualize quantidades no estoque externo a cada venda

Eventos disponíveis

O MeuCardapio.ai dispara webhooks para os seguintes eventos de pedido:

Evento	Identificador	Quando é disparado
Novo pedido	`novo_pedido`	Um novo pedido foi recebido pelo estabelecimento
Pedido aceito	`pedido_aceito`	O estabelecimento aceitou/confirmou o pedido
Em preparação	`pedido_em_preparacao`	O pedido entrou em preparação na cozinha
Pedido pronto	`pedido_pronto`	O pedido ficou pronto para retirada ou entrega
Saiu para entrega	`pedido_saiu_entrega`	O pedido saiu para entrega ao cliente
Pedido entregue	`pedido_entregue`	O pedido foi entregue ao cliente
Pedido cancelado	`pedido_cancelado`	O pedido foi cancelado
Pagamento confirmado	`pagamento_confirmado`	O pagamento online do pedido foi aprovado
Pagamento recusado	`pagamento_recusado`	O pagamento online do pedido foi recusado

Configurando um webhook

Passo 1: Acesse a tela de webhooks

No menu lateral, acesse Configurações > Integrações > Webhooks.

Passo 2: Crie um novo webhook

Clique no botao "+ Novo Webhook" para abrir o formulario de configuração.

Passo 3: Preencha os dados

Campo	Descrição	Obrigatório
URL de destino	Endereço HTTPS que receberao as notificações	Sim
Eventos	Selecione quais eventos devem disparar o webhook	Sim
Headers de autenticacao	Cabecalhos HTTP extras para autenticacao (ex: `Authorization: Bearer TOKEN`)	Não
Descrição	Nome ou descrição para identificar o webhook	Não
Ativo	Liga ou desliga o webhook sem precisar deletar	Sim

Importante

A URL de destino deve utilizar HTTPS para garantir a seguranca dos dados transmitidos. URLs HTTP não são aceitas.

Passo 4: Configure a autenticacao

Para proteger o endpoint que recebe os webhooks, adicione headers de autenticacao personalizados:

Exemplos comuns de headers:

Authorization: Bearer seu-token-secreto-aqui
X-API-Key: minha-chave-secreta
X-Webhook-Secret: segredo-compartilhado

Dica

Valide o header de autenticacao no seu servidor para garantir que as requisicoes realmente vieram do MeuCardapio.ai.

Passo 5: Salve e ative

Clique em Salvar. O webhook será criado e comecara a disparar notificações para os eventos selecionados.

Testando o webhook

Após configurar o webhook, utilize o botao "Testar" para enviar uma requisicao de teste ao seu endpoint.

Clique no botao Testar ao lado do webhook desejado
O sistema enviara um payload de teste para a URL configurada
Verifique se o seu servidor recebeu a requisicao e respondeu com status 200

informação

O payload de teste contem dados fictícios. Use-o apenas para validar que a comunicação entre o MeuCardapio.ai e o seu servidor está funcionando corretamente.

Payload JSON

Todas as notificações são enviadas via POST com o header Content-Type: application/json. Abaixo, exemplos dos payloads para cada tipo de evento.

Novo pedido (`novo_pedido`)

{
  "evento": "novo_pedido",
  "timestamp": "2026-03-31T14:30:00.000Z",
  "dados": {
    "pedido": {
      "id": 12345,
      "código": "A1B2",
      "status": "Novo",
      "horário": "2026-03-31T14:30:00.000Z",
      "cliente": {
        "nome": "João Silva",
        "telefone": "11999998888"
      },
      "itens": [
        {
          "nome": "X-Burger Especial",
          "quantidade": 2,
          "valorUnitario": 29.90,
          "total": 59.80,
          "observacao": "Sem cebola",
          "adicionais": [
            {
              "nome": "Bacon extra",
              "valor": 5.00
            }
          ]
        }
      ],
      "endereço": {
        "logradouro": "Rua das Flores",
        "número": "123",
        "complemento": "Apto 45",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "cep": "01001-000"
      },
      "pagamento": {
        "forma": "Pix",
        "status": "Pendente",
        "total": 69.80
      },
      "taxaEntrega": 10.00,
      "desconto": 0,
      "totalPedido": 69.80
    }
  }
}

Mudança de status (`pedido_em_preparacao`, `pedido_pronto`, etc.)

{
  "evento": "pedido_em_preparacao",
  "timestamp": "2026-03-31T14:35:00.000Z",
  "dados": {
    "pedido": {
      "id": 12345,
      "código": "A1B2",
      "statusAnterior": "Novo",
      "statusAtual": "Em preparação",
      "horárioAlteracao": "2026-03-31T14:35:00.000Z"
    }
  }
}

Pagamento confirmado (`pagamento_confirmado`)

{
  "evento": "pagamento_confirmado",
  "timestamp": "2026-03-31T14:32:00.000Z",
  "dados": {
    "pedido": {
      "id": 12345,
      "código": "A1B2"
    },
    "pagamento": {
      "forma": "Pix",
      "status": "Aprovado",
      "valor": 69.80,
      "códigoTransacao": "TXN-987654321"
    }
  }
}

Logs de execucao

Acompanhe o histórico de todas as chamadas feitas pelo webhook na aba Logs.

Cada registro de log mostra:

Coluna	Descrição
Data/Hora	Momento em que a chamada foi feita
Evento	Tipo do evento disparado
URL	Endereço de destino
Status HTTP	Código de resposta do servidor (200, 400, 500, etc.)
Tempo de resposta	Duração da requisicao em milissegundos
Payload	Dados enviados (clique para expandir)

Dica

Use os logs para diagnosticar problemas. Se o status HTTP for diferente de 200, verifique se a URL está correta e se o servidor está online.

Política de retentativas

Quando o servidor de destino não responde ou retorna um erro (status HTTP diferente de 2xx), o MeuCardapio.ai faz retentativas automáticas:

Tentativa	Intervalo
1a retentativa	30 segundos após a falha
2a retentativa	2 minutos após a 1a
3a retentativa	10 minutos após a 2a
4a retentativa	1 hora após a 3a

Após 4 tentativas sem sucesso, o evento será marcado como falho nos logs. O webhook permanece ativo para eventos futuros.

Atenção

Se o seu endpoint falhar repetidamente por mais de 24 horas, o webhook será desativado automáticamente. Reative-o manualmente após corrigir o problema.

Resolução de problemas

O webhook não está disparando

Verifique se o webhook está com status Ativo
Confirme que os eventos desejados estão selecionados
Acesse os Logs para verificar se ha tentativas com erro

Recebo erro 401 ou 403

O servidor de destino está rejeitando a autenticação. Verifique:

O header Authorization está correto
O token não expirou
O endpoint aceita requisicoes POST

Recebo erro 500

O servidor de destino está com erro interno. Verifique:

Os logs do seu servidor para entender a causa do erro
Se o endpoint consegue processar o payload JSON enviado

Recebo erro de timeout

O MeuCardapio.ai aguarda no máximo 10 segundos por uma resposta. Se o seu servidor demora mais:

Processe o webhook de forma assíncrona (receba, responda 200 e processe em background)
Otimize o tempo de resposta do endpoint

Os dados do payload estão incompletos

Verifique se o evento correto está selecionado
Use o botao Testar para comparar o payload esperado

Boas práticas

Responda rápido: Retorne HTTP 200 o mais rápido possível e processe os dados em segundo plano
Valide a autenticação: Sempre verifique os headers de autenticação antes de processar o payload
Trate duplicatas: Em caso de retentativas, o mesmo evento pode chegar mais de uma vez. Use o campo id do pedido para identificar duplicatas
Use HTTPS: Nunca exponha dados sensíveis em URLs HTTP
Monitore os logs: Acompanhe os logs periodicamente para identificar falhas

Perguntas frequentes

Quantos webhooks posso cadastrar?

Não há limite. Cadastre quantos webhooks forem necessários, cada um com eventos e URLs diferentes.

Posso enviar o mesmo evento para URLs diferentes?

Sim. Crie webhooks separados, cada um apontando para uma URL diferente, ambos com o mesmo evento selecionado.

Os webhooks funcionam com pedidos de iFood e 99Food?

Sim. Pedidos recebidos de qualquer origem (cardápio digital, iFood, 99Food, Keeta, balcao) disparam os mesmos eventos de webhook.

Qual o formato da data/hora no payload?

Todas as datas seguem o formato ISO 8601 (ex: 2026-03-31T14:30:00.000Z) no fuso horário UTC.

Posso pausar um webhook temporariamente?

Sim. Desative o webhook na tela de configuração. Os eventos não serao enviados enquanto estiver inativo, e não há fila de eventos perdidos.

O que acontece se meu servidor estiver fora do ar?

O sistema fará até 4 retentativas com intervalos crescentes. Se todas falharem, o evento será registrado como falho nos logs. Eventos futuros continuarao sendo disparados normalmente.

O que são webhooks?​

Casos de uso​

Eventos disponíveis​

Configurando um webhook​

Passo 1: Acesse a tela de webhooks​

Passo 2: Crie um novo webhook​

Passo 3: Preencha os dados​

Passo 4: Configure a autenticacao​

Passo 5: Salve e ative​

Testando o webhook​

Payload JSON​

Novo pedido (novo_pedido)​

Mudança de status (pedido_em_preparacao, pedido_pronto, etc.)​

Pagamento confirmado (pagamento_confirmado)​

Logs de execucao​

Política de retentativas​

Resolução de problemas​

O webhook não está disparando​

Recebo erro 401 ou 403​

Recebo erro 500​

Recebo erro de timeout​

Os dados do payload estão incompletos​

Boas práticas​

Perguntas frequentes​

Quantos webhooks posso cadastrar?​

Posso enviar o mesmo evento para URLs diferentes?​

Os webhooks funcionam com pedidos de iFood e 99Food?​

Qual o formato da data/hora no payload?​

Posso pausar um webhook temporariamente?​

O que acontece se meu servidor estiver fora do ar?​