Skip to main content

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:

Crear un webhook

Registra un endpoint de webhook para comenzar a recibir eventos.
Respuesta:

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

Respuesta:

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 un secret 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

Usa siempre comparacion en tiempo constante (como timingSafeEqual o hmac.compare_digest) al verificar firmas para prevenir ataques de temporizado.

Comportamiento de reintentos

Si tu servidor no responde con un codigo de estado 2xx 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.
Respuesta:

Ejemplos de payload por evento


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.