Presentamos Webhooks v2

El movimiento de dinero es asíncrono, y los momentos importantes ocurren al ritmo de otros. Una revisión de cumplimiento se completa. Un banco de destino liquida.

Hacer seguimiento al progreso de una transferencia en Sphere solía implicar consultar a intervalos fijos. La cobertura de webhooks no incluía el estado de las transferencias, así que los equipos escribían el loop, el GET, una comparación con lo que se había guardado la última vez y el manejo de errores para cuando la solicitud fallaba. Funcionaba, pero ponía un límite fijo a la rapidez con la que podías reaccionar y una carga constante sobre una API que, la mayor parte del tiempo, no tenía nada nuevo que decir.

Webhooks v2 ya está disponible. El motor de entrega se reconstruyó, el catálogo de eventos es nuevo y ahora los endpoints se pueden gestionar a través de la API. Dieciocho eventos cubren los ciclos de vida de la verificación de clientes y de las transferencias, y Sphere entrega cada uno a tu endpoint en el momento en que ocurre. Ahora tu handler se ejecuta cuando cambia el estado, y no según tu intervalo de polling.

La cobertura es intencional: un evento en cada paso del ciclo de vida de la transferencia, incluido el momento en que llega un depósito, y un evento en cada paso de la verificación de clientes.

Lo que ya está disponible

Antes, las transferencias solo se podían observar llamando a GET /v2/transfer/{id} de forma periódica. Ahora hay 14 eventos de transferencia que abarcan toda la máquina de estados: transfer.created, transfer.fundsReceived, transfer.processing y transfer.succeeded en el flujo exitoso, y un evento distinto para cada resultado de error, devolución y reembolso, incluidos transfer.failed, transfer.returned, transfer.refunded y transfer.expired.

Cuatro eventos cubren la verificación de clientes. customer.created se dispara una vez, cuando se crea el registro. customer.pending, customer.approved y customer.rejected se disparan una vez por perfil de verificación en cada transición, así que un cliente con dos perfiles genera dos flujos de eventos independientes.

Te suscribes por endpoint, ya sea a nombres de eventos específicos o a un comodín como transfer.*.

Por qué el payload es pequeño

Hay una decisión de diseño que vale la pena explicar aquí, porque define cómo vas a escribir tu handler.

El cuerpo de un webhook podría incluir el recurso completo. Decidimos no hacerlo, y esa decisión define cómo escribes tu handler. Cada evento incluye el ID del recurso, el estado anterior y el nuevo con sus marcas de tiempo, los IDs relacionales necesarios para asociar el evento con tus propios registros y una causa estructurada cuando algo falla:
‍
{
 "id": "event_01HXP9ZK7Q4ABC123",
 "type": "transfer.succeeded",
 "apiVersion": "v2",
 "livemode": true,
 "sequence": 5,
 "data": {
   "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
   "type": "transfer",
   "customerId": "customer_f31121c389624d3697cbf3ea8830b7a4",
   "applicationId": "application_26b980e989d94e6d975144f7e21f282f",
   "transferType": "oneTimeTransfer",
   "previousStatus": "processing",
   "previousStatusAt": "2026-04-23T14:04:30.000Z",
   "status": "succeeded",
   "statusAt": "2026-04-23T14:05:30.000Z",
   "cause": null
 }
}

El razonamiento es que la mayoría de los handlers no necesitan el objeto completo. Actualizar una fila o notificar a un canal de operaciones funciona solo con el cuerpo. Un payload pesado implicaría enviar en cada entrega campos que nunca lees. Cuando tu lógica sí necesite el recurso completo, haces un GET sobre él. Preferimos que hagas esa llamada de forma deliberada a que la pagues en cada evento.

Los errores te dicen por qué

Cada evento de error terminal incluye una cause estructurada. Un cliente rechazado llega con un valor como identity_verification_failure, document_mismatch, incomplete_information o restricted_jurisdiction. Una transferencia fallida llega con insufficient_funds, recipient_bank_rejection, invalid_recipient o quote_expired.

Son valores de enum, no texto libre. Puedes ramificar y enrutar con base en ellos sin escribir un parser para cadenas que podríamos redactar de otra forma más adelante.

El orden es un solo entero

Las redes reordenan las cosas, y un sistema de webhooks que lo ignora te traslada el problema a ti.

Cada evento incluye un sequence: un entero monótonamente creciente, con alcance en el recurso individual y en aquello a lo que se suscribe tu endpoint. Los eventos de tipos a los que no te suscribiste no lo incrementan, así que nunca verás un hueco ni te preguntarás qué te perdiste.

El patrón de conciliación es una sola comparación contra una columna de una fila que ya mantienes:

if (event.sequence <= customer.lastSphereSequence) return ack();

Sin contador global, sin servicio de ordenamiento, sin una cola propia. Ocasionalmente puedes recibir el mismo evento más de una vez; el id del evento es estable en todas las entregas del mismo evento y es tu clave de idempotencia.

Cómo verificar una entrega

Cada endpoint tiene su propio secreto de firma, que se devuelve una sola vez cuando creas el endpoint y nunca más. Cada entrega se firma con HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar:

const expected = crypto.createHmac("sha256", secret)
 .update(`${headers["sphere-timestamp"]}.${rawBody}`)
 .digest("hex");

Compara ese valor con el esquema v1= del header Sphere-Signature y rechaza cualquier entrega cuyo Sphere-Timestamp tenga más de cinco minutos de antigüedad. Verifica contra los bytes sin procesar, no contra un cuerpo re-serializado. Un paso de ida y vuelta por JSON los modificará y la firma no coincidirá.

Devuelve un 2xx en menos de quince segundos y consideraremos el evento como entregado.

En la documentación encontrarás implementaciones de verificación listas para copiar y pegar en TypeScript, Python y Go.

Gestión de endpoints

Registra un endpoint con POST /v2/webhook-endpoints, indicando los eventos que quieres recibir. Cada cuenta puede tener hasta seis.

GET /v2/events devuelve lo que te enviamos. Filtra por endpoint, tipo de evento, estado de entrega o rango de fechas, y abre cualquier evento para ver cada intento de entrega con su código de respuesta y su latencia. Son los mismos datos que alimentarán el dashboard, expuestos primero como API para que puedas construir conciliación y alertas directamente sobre ellos.

¿Ya usas webhooks?

Tus endpoints existentes siguen funcionando. Webhooks v2 es una superficie separada y versionada. Nada se activa por debajo de tus endpoints existentes. Crea un endpoint v2 a través de la API, valídalo con tu handler y retira el anterior cuando estés listo. Los endpoints existentes tendrán soporte durante al menos doce meses, y avisaremos con claridad y suficiente antelación antes de que eso cambie. Los pasos de migración están en la documentación.

Lo que viene

Un dashboard de webhooks llegará poco después de este lanzamiento. Te ofrecerá el registro de eventos como una interfaz navegable, un botón para disparar eventos de prueba contra tu endpoint antes de salir a producción y replay con un clic para cualquier entrega que no haya llegado. El replay llega con él.

Después: reintentos automáticos y monitoreo del estado de los endpoints, para que una breve caída de tu lado se recupere sin que nadie tenga que intervenir. Luego, actualización de endpoints sin recrearlos, rotación de secretos, una API de replay y SDKs oficiales para TypeScript, Python y Go. Después llegarán los eventos de documentos y de servicios.

Empieza aquí
¿Preguntas? Escríbenos a support@spherepay.co.