Envío de Datos a un Webhook

Introducción

Nuestra plataforma permite el envío de datos a un webhook proporcionado por el cliente. Este webhook debe aceptar peticiones HTTP POST y estar disponible en una URL accesible desde nuestra infraestructura.

El webhook recibirá eventos en tiempo real sobre transacciones, notificaciones u otros eventos relevantes, dependiendo de la configuración del cliente.

Requisitos del Webhook

Antes de configurar un webhook, asegúrese de que su endpoint cumple con los siguientes requisitos:

Debe aceptar solicitudes HTTP POST con datos en formato JSON.
Debe responder con un código de estado HTTP 2xx para confirmar la recepción de los datos.
Debe estar accesible desde internet, sin restricciones de firewall que bloqueen las solicitudes desde nuestros servidores.
Debe implementar la desencriptación con la llave privada, el cuerpo de las solicitudes estarán cifradas con las llaves proporcionadas en los puntos anteriores. La data se cifrará con la llave pública generada o entregada.

Formato de la Request

Cada vez que ocurra un evento relevante, nuestra plataforma enviará una solicitud HTTP POST con los siguientes elementos en el body:

{
    "message": "...",
    "...": ...,
    "data": {
        "...": "...",
        "...": ...,
        "...": "...",
    }
}

Respuesta Esperada del Webhook

El webhook debe responder con un código de estado HTTP 2xx para confirmar la recepción del evento. Si la respuesta no es 2xx, nuestra plataforma intentará reenviar la solicitud en un esquema de reintentos.

Si el webhook no responde o devuelve un código diferente a 2xx, se reintentará el envío con la siguiente estrategia:

Primer reintento: 1 minuto después del primer intento fallido.
Segundo reintento: 5 minutos después del segundo intento fallido.
Tercer reintento: 15 minutos después del tercer intento fallido.
Último reintento: 1 hora después del intento anterior.

Si después de estos intentos el webhook sigue fallando, se desactiva temporalmente y se notificará al cliente para que tome acción.

Seguridad y Validación

Para garantizar la seguridad de los datos enviados al webhook, se recomienda implementar:

HTTPS: No se recomienda recibir datos a webhooks con http://, en su lugar debería ser a https:// webhooks.
Rate Limiting: Para evitar abuso, se recomienda implementar límites en la cantidad de solicitudes aceptadas por minuto.

Errores Comunes y Soluciones

A continuación, se presentan algunos errores frecuentes y cómo solucionarlos:

Error	Posible Causa	Solución
400 Bad Request	El webhook no está aceptando JSON o hay un problema en el formato.	Verifique que el webhook acepte `Content-Type: application/json` y que el body esté bien formado.
500 Internal Server Error	Error en la aplicación del cliente.	Revise los logs del servidor y asegúrese de que el webhook está funcionando correctamente.
Timeout	El webhook tarda demasiado en responder.	Asegúrese de procesar la solicitud en menos de 5 segundos.