Webhooks
Recibe notificaciones automáticas de eventos en tu sistema
¿Qué es un webhook?
Un webhook es una notificación HTTP que Recaudo envía a tu servidor cuando ocurre un evento importante, como un pago exitoso o un reembolso. Esto te permite automatizar procesos en tu sistema sin necesidad de consultar constantemente nuestra API.
Eventos disponibles
Recaudo puede notificarte sobre los siguientes eventos:
payment.succeeded
Un pago se completó exitosamente.
payment.failed
Un intento de pago falló.
payment.refunded
Se procesó un reembolso total o parcial.
payment_link.paid
Un link de pago fue pagado.
payment_link.expired
Un link de pago expiró sin ser pagado.
Configurar un webhook
- Ve a Configuración → Webhooks
- Haz clic en Agregar endpoint
- Ingresa la URL de tu servidor que recibirá las notificaciones
- Selecciona los eventos que deseas recibir
- Guarda la configuración
Se generará un secreto de firma que debes guardar de forma segura. Este secreto te permite verificar que las notificaciones provienen de Recaudo.
Estructura del webhook
Cada notificación incluye:
{
"id": "evt_abc123",
"type": "payment.succeeded",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"payment_id": "pay_xyz789",
"amount": 1500.00,
"currency": "MXN",
"customer_email": "cliente@ejemplo.com"
}
}Reintentos automáticos
Si tu servidor no responde con un código 2xx, Recaudo reintentará el envío:
- 1er reintento: 5 minutos después
- 2do reintento: 30 minutos después
- 3er reintento: 2 horas después
- 4to reintento: 24 horas después
Después del 4to intento fallido, el webhook se marca como fallido y no se reintenta más.
Verificar la firma
Siempre verifica la firma del webhook para asegurarte de que proviene de Recaudo:
// PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RECAUDO_SIGNATURE'];
$secret = 'tu_secreto_de_firma';
$expected = hash_hmac('sha256', $payload, $secret);
if (hash_equals($expected, $signature)) {
// Firma válida, procesar el webhook
}Importante