Webhooks en EvolutionAPI
Cómo configurar y recibir webhooks de EvolutionAPI con reintentos, idempotencia y seguridad en producción, con ejemplos de payload reales.
EvolutionAPI envía eventos vía webhook HTTP POST a una URL que tú defines. El webhook es la forma en que tu automatización (n8n, tu propia API, etc.) sabe que llegó un mensaje.
Eventos disponibles
| Evento | Cuándo se dispara |
|---|---|
MESSAGES_UPSERT | Mensaje recibido o enviado |
MESSAGES_UPDATE | Cambió el estado (entregado, leído) |
CONNECTION_UPDATE | Se conectó/desconectó |
PRESENCE_UPDATE | ”Escribiendo…” / en línea |
QRCODE_UPDATED | Nuevo QR para vincular |
Configurar el webhook global
Configúralo al momento de crear la instancia:
curl -X POST https://sua-evolution.rollinhost.com.br/instance/create \
-H "Content-Type: application/json" \
-H "apikey: SUA_API_KEY" \
-d '{
"instanceName": "atendimento",
"qrcode": true,
"webhook": {
"url": "https://seu-n8n.exemplo.com/webhook/whats-in",
"events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
"webhook_by_events": false
}
}'Estructura del payload
{
"event": "messages.upsert",
"instance": "atendimento",
"data": {
"key": {
"remoteJid": "5511999999999@s.whatsapp.net",
"fromMe": false,
"id": "3EB0..."
},
"pushName": "João Silva",
"message": {
"conversation": "Oi, gostaria de saber sobre os planos"
},
"messageTimestamp": 1735689600
}
}Reintentos e idempotencia
Buenas prácticas:
- Devuelve siempre 200 rápidamente (< 5s) y procesa en una cola
- Idempotencia por
data.key.id: los webhooks pueden llegar duplicados en una reconexión - Persiste el raw event antes de procesarlo (si hay un bug, lo reprocesas)
Seguridad
EvolutionAPI no firma los webhooks por defecto. Para garantizar que la solicitud vino de ella:
- Restringe por IP en el firewall (solo la IP del servidor de Evolution)
- Usa una URL con path secreto (
/webhook/abc123-supersecreto) - Valida un
apikeypersonalizado en el header (configúralo en n8n para verificarlo)
Próximos pasos
Última actualización:
