Maytapi/Documentação//webhook
/webhookEventos em tempo real em JSONAPI de webhooks do WhatsApp
Receba no seu próprio servidor as mensagens do WhatsApp, as confirmações de entrega e leitura e as mudanças de status da sessão no momento em que acontecem. Configure uma URL e todos os números conectados enviam seus eventos para ela em JSON.
- mensagens recebidas
- confirmações de entrega e leitura
- status da sessão
- uma URL para todos os números

Quatro tipos de evento, um só endpoint
Todo evento tem um campo type, então um único endpoint pode encaminhar mensagens, confirmações e mudanças de status de todos os seus números.
-
type: message
Mensagens recebidas
Texto, imagens, vídeo, áudio, documentos, localizações e cartões de contato enviados ao seu número, com o remetente e o id da conversa.
-
type: ack
Confirmações de entrega e leitura
Saiba quando uma mensagem enviada foi entregue, chegou ao celular, foi vista, reproduzida ou apagada.
-
type: status
Status da sessão
Seja avisado quando um celular fica ativo, aguarda leitura do QR, fica ocioso ou informa um erro.
-
live chat
Eventos do chat ao vivo
Usando a API junto com o LiveChat, os eventos dos atendentes chegam ao mesmo webhook.
-
phone_id
Roteamento de vários números
Cada evento traz product_id e phone_id, então um endpoint atende todos os números da sua conta.
-
reply
URL de resposta pronta
As mensagens recebidas trazem uma URL reply: responder ao cliente é uma única requisição POST.
Configure seu webhook com uma requisição
Envie seu endpoint HTTPS para /setWebhook uma vez. A partir daí, cada celular conectado ao seu produto envia seus eventos para essa URL em JSON.
- ✓Uma URL para todos os números conectados
- ✓JSON simples via HTTPS POST
- ✓Altere quando quiser pelo painel ou pela API
curl -X POST "https://api.maytapi.com/api/$PID/setWebhook" \
-H "x-maytapi-key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"webhook": "https://example.com/maytapi/webhook"}'await fetch(`https://api.maytapi.com/api/${PID}/setWebhook`, {
method: "POST",
headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({ webhook: "https://example.com/maytapi/webhook" })
});import requests
requests.post(
f"https://api.maytapi.com/api/{PID}/setWebhook",
headers={"x-maytapi-key": TOKEN},
json={"webhook": "https://example.com/maytapi/webhook"},
timeout=10,
)$ch = curl_init("https://api.maytapi.com/api/$pid/setWebhook");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["x-maytapi-key: $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["webhook" => "https://example.com/maytapi/webhook"]),
]);
echo curl_exec($ch);Mensagens e confirmações na hora
O cliente escreve e seu servidor fica sabendo. Você envia uma mensagem e as confirmações de entrega e leitura chegam em segundos, sem consultas periódicas.
- ✓Retorne HTTP 200 para confirmar o evento
- ✓Processe eventos de forma assíncrona em alto volume
- ✓Use msgId para associar confirmações às mensagens enviadas
"type": "text", "text": "Meu pedido já foi enviado?""ackCode": 1, "ackType": "delivered""ackCode": 2, "ackType": "reached""ackCode": 3, "ackType": "seen""status": "active"Como é um evento
Os eventos são objetos JSON compactos. O campo type diz como tratá-lo; product_id e phone_id dizem a qual conta e número ele pertence.
- ✓message: texto, mídia, localização, vCard e mais
- ✓ack: progresso da entrega com ackCode e ackType
- ✓status: active, qr-code, idle, phone-error, loading, disabled
{
"type": "message",
"product_id": "1a2b3c4d-…",
"phone_id": 12345,
"user": {
"id": "55119xxxxxx67@c.us",
"name": "Customer",
"phone": "55119xxxxxx67"
},
"message": {
"id": "3EB081AF26FADE6416D8",
"type": "text",
"text": "Is my order shipped?",
"fromMe": false
},
"conversation": "55119xxxxxx67@c.us",
"receiver": "55119xxxxxx21",
"timestamp": 1574081887,
"reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}{
"type": "ack",
"product_id": "1a2b3c4d-…",
"data": [
{
"ackType": "seen",
"ackCode": 3,
"chatId": "55119xxxxxx67@c.us",
"msgId": "3EB0A1B2C3D4E5F6",
"time": 1586874663
}
]
}{
"type": "status",
"pid": "1a2b3c4d-…",
"phone_id": 12345,
"status": "active"
}Entrega e leitura, código por código
Os eventos ack mostram até onde cada mensagem enviada chegou. Se não precisar deles, desative com /setAckPreference e receba só as mensagens recebidas.
- ✓Áudios também avisam quando são reproduzidos
- ✓Mensagens apagadas também são informadas
| ackType | ackCode | Significado |
|---|---|---|
| delivered | 1 | Entregue aos servidores do WhatsApp |
| reached | 2 | Chegou ao celular do destinatário |
| seen | 3 | Vista pelo destinatário |
| played | 4 | Mensagem de voz reproduzida |
| deleted | 5 | Apagada pelo usuário |
Responda a partir do mesmo evento
As mensagens recebidas trazem uma URL reply pronta. Confirme o webhook rapidamente e depois envie sua resposta — um padrão simples para respostas automáticas e chatbots.
- ✓Funciona com qualquer linguagem ou framework
- ✓Ignore suas próprias mensagens com message.fromMe
app.post("/maytapi/webhook", express.json(), async (req, res) => {
res.sendStatus(200); // acknowledge first
const event = req.body;
if (event.type !== "message" || event.message.fromMe) return;
await fetch(event.reply, {
method: "POST",
headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({
to_number: event.conversation,
type: "text",
message: "Thanks! We received your message."
})
});
});@app.post("/maytapi/webhook")
def webhook():
event = request.get_json()
if event.get("type") == "message" and not event["message"]["fromMe"]:
requests.post(
event["reply"],
headers={"x-maytapi-key": TOKEN},
json={
"to_number": event["conversation"],
"type": "text",
"message": "Thanks! We received your message.",
},
timeout=10,
)
return "", 200O que as equipes constroem com o webhook
-
Sincronização com CRM e helpdesk
Cada mensagem recebida no WhatsApp vira automaticamente um ticket ou registro no seu CRM.
-
Chatbots e agentes de IA
Passe as mensagens recebidas ao seu bot ou agente de IA e responda em tempo real pela URL reply.
-
Rastreio de entregas
Guarde as confirmações de entrega e leitura para saber quais avisos de pedido os clientes realmente viram.
-
Monitoramento de sessões
Avise sua equipe quando um número precisar de nova leitura de QR ou informar um erro.
-
Automações sem código
Aponte o webhook para o n8n ou Make e crie fluxos sem escrever um backend.
-
Caixa compartilhada
Encaminhe conversas de vários números para a pessoa certa da equipe.
Perguntas frequentes sobre webhooks do WhatsApp
Pergunte o que quiser ao nosso suporte pelo WhatsApp. O tempo médio de resposta é inferior a 24 horas.
Central de ajuda →O que é um webhook do WhatsApp?
Um webhook é uma URL no seu servidor que a Maytapi chama com uma requisição HTTPS POST sempre que algo acontece no seu número de WhatsApp: uma nova mensagem, uma confirmação de entrega ou leitura ou uma mudança de status da sessão.
Quais eventos chegam ao meu webhook?
Mensagens recebidas (type: message), confirmações de entrega e leitura (type: ack), mudanças de status da sessão (type: status) e, se você usa a API com o LiveChat, eventos do chat ao vivo.
Preciso de uma URL HTTPS pública?
Sim. O webhook precisa ser acessível pela internet. Durante o desenvolvimento, você pode expor seu servidor local com um túnel como o ngrok.
Um webhook pode atender vários números?
Sim. O webhook é configurado por produto e cada evento traz o phone_id, então um único endpoint atende todos os números da sua conta.
Posso desativar as confirmações de entrega e leitura?
Sim. Chame /setAckPreference com ack_delivery igual a false e seu webhook receberá apenas mensagens recebidas e mudanças de status.

Pegue sua chave e envie a primeira mensagem em dez minutos
Sem aprovação, sem templates, sem cartão. Todos os endpoints liberados por três dias.