Skip to main content
Los webhooks permiten que SpherePay notifique a tu aplicación en el momento en que algo sucede — un cliente es aprobado, una transferencia tiene éxito, se reciben fondos — para que ya no tengas que revisar endpoints GET en busca de cambios. Registras un endpoint HTTPS, eliges los eventos que te interesan, y SpherePay entrega un payload JSON firmado a ese endpoint cada vez que ocurre uno de esos eventos.

​
Cómo funciona

  1. Registra un endpoint de webhook. Llama a POST /v2/webhook-endpoints con tu URL y la lista de eventos a los que quieres suscribirte. La respuesta incluye un secreto de firma — guárdalo de forma segura; se muestra exactamente una vez.
  2. Ocurre un evento. Un recurso en tu aplicación cambia de estado — por ejemplo, una transferencia pasa de processing a succeeded.
  3. SpherePay entrega el evento. SpherePay envía un POST HTTP a cada endpoint habilitado suscrito a ese tipo de evento. La solicitud lleva un payload firmado que describe la transición de estado.
  4. Tú verificas y procesas. Tu handler verifica la firma, aplica el cambio de estado y responde con un código de estado 2xx dentro de 15 segundos.

​
Conceptos centrales

El sistema de webhooks de SpherePay rastrea tres registros distintos para cada notificación, y los tres son visibles a través de la API de Eventos: Cada registro lleva su propio identificador y sus propias marcas de tiempo — consulta Payloads de eventos para ver cómo se mapean al cuerpo y a los encabezados del payload, y en cuáles confiar al ordenar el estado.

​
Semántica de entrega

Entender estas garantías es esencial para construir un consumidor confiable:
  • Entrega al menos una vez (at-least-once). Ocasionalmente puedes recibir el mismo evento más de una vez. Deduplica usando el id del evento en el cuerpo — es estable a través de cada entrega y reenvío del mismo evento.
  • Sin reintentos automáticos. SpherePay hace exactamente un intento de entrega por evento por endpoint. Si tu endpoint devuelve una respuesta no 2xx, o no responde dentro de 15 segundos, la entrega se marca como failed y SpherePay no la reintenta automáticamente. Puedes reenviar una entrega fallida en cualquier momento vía la API de Eventos.
  • El orden de entrega no está garantizado. Los reenvíos, los workers en paralelo y las variaciones de red pueden causar llegadas fuera de orden. Cada payload lleva un campo sequence para que puedas detectar y descartar actualizaciones obsoletas.
  • Payloads mínimos. Los payloads de eventos describen la transición de estado — el estado anterior y el nuevo estado — no el recurso completo. Cuando necesites el objeto completo, llama al endpoint GET del recurso. Consulta Payloads de eventos.
Debido a que no hay reintentos automáticos en la versión actual, haz que tu handler de webhooks sea rápido y resiliente: confirma con un 2xx inmediatamente después de verificar la firma, y realiza el procesamiento pesado de forma asíncrona. Un handler lento que exceda la ventana de 15 segundos causará que las entregas se marquen como failed.

​
Responder a una entrega

Devuelve cualquier código de estado 2xx para confirmar la recepción. Cualquier otra cosa — incluidas las redirecciones, que SpherePay no sigue — marca la entrega como failed.

​
Explora

Gestiona endpoints de webhook

Registra, lista y elimina endpoints de webhook, y entiende los límites y estados de los endpoints.

Payloads de eventos

La estructura de la envoltura, el campo sequence, y cómo applicationId delimita cada evento.

Catálogo de eventos

Cada tipo de evento al que puedes suscribirte, con sus desencadenantes y payloads de ejemplo.

Verifica firmas

Autentica las entregas con HMAC-SHA256 — con fragmentos de código en Python, JavaScript, Go, Java y C#.

Eventos y reenvíos

Explora tu historial de eventos, inspecciona intentos de entrega y reenvía entregas fallidas.
Última modificación el 11 de agosto de 2026