Configuración
Webhooks
Avisa a tus otros sistemas en el momento en que pasa algo en Recaudo: un pago, un cliente nuevo, una conversación asignada.
Antes de empezar
Necesitas una dirección https en tu sistema que reciba peticiones POST con JSON. Los webhooks están en Configuración › Avanzado › Webhooks (página Avisos a tus sistemas).
Agregar una dirección
Cada dirección recibe solo los eventos que elijas.
-
Abre Webhooks
Entra a Configuración, abre Avanzado, elige Webhooks y haz clic en Nueva dirección. -
Escribe a dónde avisar
En A dónde avisar pega la Dirección web (debe empezar con https) y, si quieres, un nombre o nota. Deja marcada Mandar avisos a esta dirección. -
Elige qué avisar
En Qué avisar marca los eventos que te interesan o usa Seleccionar todos. -
Guarda y copia la llave de firma
Haz clic en Guardar dirección. Aparece Guarda tu llave de firma (empieza conwhsec_): cópiala a tu sistema. -
Manda una prueba
Usa Enviar prueba para recibir un avisotest.webhooky confirmar que tu sistema responde.
Cuidado
La llave de firma se muestra una sola vez. Si la pierdes, entra al detalle de la dirección y usa Cambiar llave de firma en Datos técnicos; la anterior deja de servir.
Eventos disponibles
Los eventos se agrupan por módulo. Algunos ejemplos:
- Pagos y links de pago:
payment.succeeded,payment.failed,payment_link.paid. - Facturas y suscripciones:
invoice.paid,subscription.canceled. - Clientes y leads:
customer.created,lead.converted. - Conversaciones:
conversation.assigned,conversation.message.received. - CRM, seguimientos y flujos:
deal.won,follow_up.completed,flow_run.completed.
Verificar la firma
Cada aviso trae el encabezado X-Recaudo-Signature con la hora (t) y una firma HMAC-SHA256 (v1) de t.cuerpo hecha con tu llave de firma. Calcúlala tú y compárala antes de confiar en el aviso:
X-Recaudo-Signature: t=1760000000,v1=5f2b9c...
X-Recaudo-Event-Id: 9b1d2c3e-...
X-Recaudo-Event-Type: payment.succeeded
<?php
$secret = getenv('RECAUDO_WEBHOOK_SECRET'); // whsec_...
$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_RECAUDO_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts); // t=...&v1=...
$expected = hash_hmac('sha256', $parts['t'] . '.' . $payload, $secret);
if (! hash_equals($expected, $parts['v1'] ?? '') || abs(time() - (int) $parts['t']) > 300) {
http_response_code(400);
exit;
}
$event = json_decode($payload, true);
http_response_code(200);
const crypto = require('crypto');
// Usa el cuerpo crudo (raw body), no el JSON ya interpretado
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}
La estructura de cada evento está en la referencia de webhooks de la API.
Revisar envíos y reenviar
Tu sistema debe contestar con un código 2xx. Si no responde o falla, Recaudo reintenta hasta 5 veces con esperas cada vez más largas.
-
Abre el detalle
En la lista de direcciones haz clic en Ver detalle. -
Revisa Envíos recientes
Cada envío aparece como Recibido, Fallido o Pendiente, con el número de intento, los datos enviados y la respuesta de tu sistema. -
Reenvía si hace falta
Cuando corrijas el problema en tu sistema, usa Reenviar en el envío que falló.
Importante
No lo confundas con Configuración › Avanzado › Registro de webhooks: ahí están los avisos que tus pasarelas de pago le mandan a Recaudo, no los que Recaudo te manda a ti.
Tip
Usa
X-Recaudo-Event-Id para ignorar avisos repetidos: con los reintentos, el mismo evento puede llegarte más de una vez.Siguiente paso
¿Te sirvió esta página?
Gracias por avisarnos.