Maytapi/Documentación//webhook
/webhookEventos en tiempo real en JSONAPI de webhooks de WhatsApp
Recibe en tu propio servidor los mensajes entrantes de WhatsApp, las confirmaciones de entrega y lectura y los cambios de estado de la sesión en el momento en que ocurren. Configura una URL y todos los números conectados envían allí sus eventos en JSON.
- mensajes entrantes
- confirmaciones de entrega y lectura
- estado de la sesión
- una URL para todos los números

Cuatro tipos de evento, un solo endpoint
Cada evento tiene un campo type, así un único endpoint puede enrutar mensajes, confirmaciones y cambios de estado de todos tus números.
-
type: message
Mensajes entrantes
Texto, imágenes, vídeo, audio, documentos, ubicaciones y tarjetas de contacto enviados a tu número, con el remitente y el id de la conversación.
-
type: ack
Confirmaciones de entrega y lectura
Sabe cuándo un mensaje enviado se entregó, llegó al teléfono, se vio, se reprodujo o se eliminó.
-
type: status
Estado de la sesión
Recibe un aviso cuando un teléfono pasa a activo, espera un escaneo QR, queda inactivo o informa de un error.
-
live chat
Eventos de chat en vivo
Si usas la API junto con LiveChat, los eventos de los agentes llegan al mismo webhook.
-
phone_id
Enrutamiento multinúmero
Cada evento incluye product_id y phone_id, así un endpoint sirve a todos los números de tu cuenta.
-
reply
URL de respuesta lista
Los mensajes entrantes incluyen una URL reply: responder al cliente es una sola petición POST.
Configura tu webhook con una petición
Envía tu endpoint HTTPS a /setWebhook una vez. A partir de ahí, cada teléfono conectado a tu producto envía sus eventos a esa URL en JSON.
- ✓Una URL para todos los números conectados
- ✓JSON simple mediante HTTPS POST
- ✓Cámbiala cuando quieras desde el panel o la 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);Mensajes y confirmaciones al instante
Un cliente escribe y tu servidor lo sabe. Envías un mensaje y las confirmaciones de entrega y lectura llegan en segundos, sin consultas periódicas.
- ✓Devuelve HTTP 200 para confirmar el evento
- ✓Procesa los eventos de forma asíncrona con mucho volumen
- ✓Usa msgId para relacionar confirmaciones y mensajes
"type": "text", "text": "¿Ya se envió mi pedido?""ackCode": 1, "ackType": "delivered""ackCode": 2, "ackType": "reached""ackCode": 3, "ackType": "seen""status": "active"Cómo es un evento
Los eventos son objetos JSON compactos. El campo type indica cómo tratarlo; product_id y phone_id indican a qué cuenta y número pertenece.
- ✓message: texto, multimedia, ubicación, vCard y más
- ✓ack: progreso de entrega con ackCode y ackType
- ✓status: active, qr-code, idle, phone-error, loading, disabled
{
"type": "message",
"product_id": "1a2b3c4d-…",
"phone_id": 12345,
"user": {
"id": "3461xxxxx67@c.us",
"name": "Customer",
"phone": "3461xxxxx67"
},
"message": {
"id": "3EB081AF26FADE6416D8",
"type": "text",
"text": "Is my order shipped?",
"fromMe": false
},
"conversation": "3461xxxxx67@c.us",
"receiver": "3461xxxxx21",
"timestamp": 1574081887,
"reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}{
"type": "ack",
"product_id": "1a2b3c4d-…",
"data": [
{
"ackType": "seen",
"ackCode": 3,
"chatId": "3461xxxxx67@c.us",
"msgId": "3EB0A1B2C3D4E5F6",
"time": 1586874663
}
]
}{
"type": "status",
"pid": "1a2b3c4d-…",
"phone_id": 12345,
"status": "active"
}Entrega y lectura, código a código
Los eventos ack indican hasta dónde llegó cada mensaje enviado. Si no los necesitas, desactívalos con /setAckPreference y recibe solo los mensajes entrantes.
- ✓Las notas de voz también avisan cuando se reproducen
- ✓También se notifican los mensajes eliminados
| ackType | ackCode | Significado |
|---|---|---|
| delivered | 1 | Entregado a los servidores de WhatsApp |
| reached | 2 | Llegó al teléfono del destinatario |
| seen | 3 | Visto por el destinatario |
| played | 4 | Mensaje de voz reproducido |
| deleted | 5 | Eliminado por el usuario |
Responde desde el mismo evento
Los mensajes entrantes incluyen una URL reply lista. Confirma el webhook rápido y después envía tu respuesta: un patrón sencillo para respuestas automáticas y chatbots.
- ✓Funciona con cualquier lenguaje o framework
- ✓Ignora tus propios mensajes con 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 "", 200Qué construyen los equipos con el webhook
-
Sincronización con CRM y helpdesk
Cada mensaje entrante de WhatsApp se convierte automáticamente en un ticket o una entrada en tu CRM.
-
Chatbots y agentes de IA
Pasa los mensajes entrantes a tu bot o agente de IA y responde en tiempo real con la URL reply.
-
Seguimiento de entregas
Guarda las confirmaciones de entrega y lectura para saber qué avisos de pedido vieron realmente los clientes.
-
Monitorización de sesiones
Avisa a tu equipo cuando un número necesita un nuevo escaneo QR o informa de un error.
-
Automatizaciones sin código
Apunta el webhook a n8n o Make y crea flujos sin escribir un backend.
-
Bandeja compartida
Dirige las conversaciones de varios números a la persona adecuada del equipo.
Preguntas frecuentes sobre webhooks de WhatsApp
Pregunta lo que quieras a nuestro equipo de soporte por WhatsApp. El tiempo medio de respuesta es inferior a 24 horas.
Centro de ayuda →¿Qué es un webhook de WhatsApp?
Un webhook es una URL de tu servidor a la que Maytapi llama con una petición HTTPS POST cada vez que ocurre algo en tu número de WhatsApp: un mensaje entrante, una confirmación de entrega o lectura o un cambio de estado de la sesión.
¿Qué eventos llegan a mi webhook?
Mensajes entrantes (type: message), confirmaciones de entrega y lectura (type: ack), cambios de estado de la sesión (type: status) y, si usas la API con LiveChat, eventos del chat en vivo.
¿Necesito una URL HTTPS pública?
Sí. El webhook debe ser accesible desde internet. Durante el desarrollo puedes exponer tu servidor local con un túnel como ngrok.
¿Un webhook puede atender varios números?
Sí. El webhook se configura por producto y cada evento incluye el phone_id, así que un único endpoint sirve a todos los números de tu cuenta.
¿Puedo desactivar las confirmaciones de entrega y lectura?
Sí. Llama a /setAckPreference con ack_delivery en false y tu webhook recibirá solo mensajes entrantes y cambios de estado.

Consigue tu clave y envía tu primer mensaje en diez minutos
Sin aprobación, sin plantillas, sin tarjeta. Todos los endpoints abiertos durante tres días.