Recaudo Docs

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.

  1. Abre Webhooks

    Entra a Configuración, abre Avanzado, elige Webhooks y haz clic en Nueva dirección.
  2. 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.
  3. Elige qué avisar

    En Qué avisar marca los eventos que te interesan o usa Seleccionar todos.
  4. Guarda y copia la llave de firma

    Haz clic en Guardar dirección. Aparece Guarda tu llave de firma (empieza con whsec_): cópiala a tu sistema.
  5. Manda una prueba

    Usa Enviar prueba para recibir un aviso test.webhook y confirmar que tu sistema responde.

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

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.

  1. Abre el detalle

    En la lista de direcciones haz clic en Ver detalle.
  2. 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.
  3. Reenvía si hace falta

    Cuando corrijas el problema en tu sistema, usa Reenviar en el envío que falló.

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.
Esc