Webhooks

Utiliza los webhooks para reaccionar a los cambios asíncronos. La entrega es al menos una vez, por lo que los eventos duplicados, retrasados y fuera de orden son normales.

Registra solo los eventos que necesitas

Crea un endpoint con POST /v3/webhooks. Suscríbete solo a eventos documentados que impulsen tu integración. Este ejemplo utiliza transfer.state_changed.

Create webhook endpoint

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

curl --request POST \
  "${API_BASE}/v3/webhooks" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: webhook-endpoint-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "url": "https://example.com/webhooks/swipelux",
  "events": ["transfer.state_changed"]
}
JSON

Guarda data.id de la respuesta como WEBHOOK_ID. Solicita una URL de portal a GET /v3/webhooks/portal con una clave de API que tenga webhooks:write, obtén el secreto de firma de este endpoint y guárdalo por separado de tu clave de API en un gestor de secretos. La URL del portal concede acceso por sí sola y caduca al cabo de una hora, así que solicita una nueva cada vez y no la guardes ni la compartas. El portal agrupa los eventos v3 por recurso: Customers, Capabilities, Accounts, Recipients, Transfers y API. Cada evento muestra su esquema de payload y un ejemplo. Los eventos heredados se marcan como obsoletos y se listan en un grupo Legacy independiente. Si tu endpoint ya está suscrito a un evento heredado, lo sigue recibiendo. Elige nombres de eventos v3 para las nuevas suscripciones.

Cambia los eventos de un endpoint

Lee un endpoint con GET /v3/webhooks/{webhookId}. La respuesta tiene la misma forma de events que GET /v3/webhooks. Nunca incluye el secreto de firma. Las lecturas requieren webhooks:read y devuelven 404 not_found para un ID de endpoint desconocido. Actualiza el endpoint con PATCH /v3/webhooks/{webhookId}. Envía una cabecera Idempotency-Key. Las actualizaciones requieren webhooks:write.

Envía solo events para conservar la URL actual.
Envía solo url para conservar la selección de eventos actual.
events reemplaza toda la selección. Lee primero el endpoint e incluye todos los eventos que sigas necesitando.
Las nuevas suscripciones deben usar nombres de eventos v3.
Puedes conservar un nombre de evento heredado si el endpoint ya está suscrito a él. Añadir un nuevo nombre heredado devuelve 400 validation_error.

Este cuerpo conserva la URL y reemplaza la selección:

Request body

{
  "events": ["transfer.state_changed", "capability.status_changed"]
}

Verifica antes de analizar

Swipelux entrega las nuevas integraciones de webhooks mediante Svix. Verifica el cuerpo bruto de la solicitud con el secreto de firma de tu endpoint y estas cabeceras:

svix-id
svix-timestamp
svix-signature

No analices el JSON ni provoques efectos secundarios antes de que la verificación tenga éxito.

Verify signature

import { Webhook } from "svix";

const verifier = new Webhook(process.env.SWIPELUX_WEBHOOK_SECRET);

export async function handleSwipeluxWebhook(request) {
  const rawBody = await request.text();
  const event = verifier.verify(rawBody, {
    "svix-id": request.headers.get("svix-id"),
    "svix-timestamp": request.headers.get("svix-timestamp"),
    "svix-signature": request.headers.get("svix-signature"),
  });

  await webhookInbox.insertIfAbsent({
    id: event.id,
    payload: event,
    status: "pending",
  });

  return new Response(null, { status: 204 });
}

Rechaza las solicitudes con firmas ausentes o inválidas. Mantén disponible el cuerpo bruto hasta que se complete la verificación.

Persiste, reconoce y luego procesa

Coloca una restricción de unicidad sobre el id del envelope. Persiste el envelope verificado, devuelve 2xx con prontitud y luego procésalo de forma asíncrona. Si el ID del evento ya existe, reconoce la entrega sin repetir los efectos secundarios completados. Reanuda el trabajo local pendiente o fallido mediante tu propia cola de reintentos. No utilices el campo attempt del envelope como clave de deduplicación ni como contador de reintentos de transporte.

Vuelve a obtener el estado actual

El orden de los webhooks no es un historial autoritativo del recurso. Utiliza resource.type y resource.id para localizar el objeto y luego obtén su estado actual antes de actualizar tu sistema. Para un evento de transferencia, llama a GET /v3/transfers/{transferId}:

Refetch transfer

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Impulsa el estado visible al cliente y las acciones posteriores a partir de la respuesta actual de la API. Diseña los efectos secundarios para que se mantengan seguros si dos workers procesan eventos relacionados en un orden distinto.

Recupera las entregas

Utiliza GET /v3/webhooks/portal para abrir los registros de entrega. Con webhooks:write, también puedes reintentar entregas fallidas o iniciar un replay manual. Una clave con solo webhooks:read abre un portal que muestra las entregas, pero no puede reintentarlas, repetirlas ni revelar los secretos de firma. Cada replay debe pasar por la misma verificación de firma y el mismo buzón durable. Para recuperarte tras una caída, replaya la ventana afectada y vuelve a obtener cada recurso referenciado. Los IDs de evento completados siguen siendo no-ops; los registros incompletos se reanudan de forma asíncrona. A continuación, verifica las entregas duplicadas y fuera de orden en sandbox y completa la lista de comprobación de Go live.

Comienza

Incorpora clientes

Crea flujos de dinero

Lanzamiento

Registra solo los eventos que necesitas

Cambia los eventos de un endpoint

Verifica antes de analizar

Persiste, reconoce y luego procesa

Vuelve a obtener el estado actual

Recupera las entregas

​Registra solo los eventos que necesitas

​Cambia los eventos de un endpoint

​Verifica antes de analizar

​Persiste, reconoce y luego procesa

​Vuelve a obtener el estado actual

​Recupera las entregas

Registra solo los eventos que necesitas

Cambia los eventos de un endpoint

Verifica antes de analizar

Persiste, reconoce y luego procesa

Vuelve a obtener el estado actual

Recupera las entregas