Webhooks
Los webhooks te permiten recibir callbacks HTTP en tiempo real cuando ocurren eventos en tus instancias de WhatsApp. En lugar de consultar la API periodicamente, Wappfy envia los eventos a tu servidor a medida que ocurren.Eventos soportados
Wappfy soporta 12 tipos de eventos de webhook:Eventos de mensaje
Eventos de mensaje
Eventos de instancia
Eventos de instancia
Eventos de grupo y contacto
Eventos de grupo y contacto
Crear un webhook
Registra un endpoint de webhook para comenzar a recibir eventos.Opciones de configuracion
El campo
instance_id es opcional. Si se omite, el webhook recibira eventos de todas las instancias de tu cuenta.Listar webhooks
Actualizar un webhook
Actualiza la URL, los eventos o la configuracion de un webhook existente.Eliminar un webhook
Formato del payload de entrega
Cuando ocurre un evento, Wappfy envia una solicitud POST a la URL de tu webhook con la siguiente estructura:Campos del payload
Verificacion de firma HMAC
Si proporcionas unsecret al crear un webhook, cada entrega incluira un header X-Wappfy-Signature con una firma HMAC-SHA256 del cuerpo de la solicitud.
Verifica siempre esta firma para asegurar que la solicitud proviene de Wappfy y no fue alterada.
Ejemplos de verificacion
Comportamiento de reintentos
Si tu servidor no responde con un codigo de estado2xx dentro del timeout_ms configurado, Wappfy reintentara la entrega.
Los reintentos se detienen cuando se recibe una respuesta
2xx o se agota el retry_count. El conteo de reintentos predeterminado es 3.Ver historial de entregas
Consulta el registro de entregas de un webhook para ver los intentos de entrega pasados y sus resultados.Ejemplos de payload por evento
message.received
message.received
message.delivered
message.delivered
message.read
message.read
message.reaction
message.reaction
instance.connected
instance.connected
instance.qr
instance.qr
group.joined
group.joined
Buenas practicas
Responder rapidamente
Devuelve un estado
200 dentro de 5 segundos. Procesa el evento de forma asincrona para evitar tiempos de espera.Deduplicar
Usa el
id de entrega para detectar y omitir entregas duplicadas causadas por reintentos.Verificar firmas
Valida siempre el header
X-Wappfy-Signature si configuraste un secreto.Usar HTTPS
Las URLs de webhook deben usar HTTPS. Los endpoints HTTP seran rechazados.