Webhooks

Utilitza els webhooks per reaccionar a canvis asíncrons. El lliurament és almenys una vegada, de manera que els esdeveniments duplicats, retardats i fora d’ordre són normals.

Registra només els esdeveniments que necessites

Crea un endpoint amb POST /v3/webhooks. Subscriu-te només als esdeveniments documentats que impulsen la teva integració. Aquest exemple utilitza 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

Emmagatzema data.id de la resposta com a WEBHOOK_ID. Sol·licita una URL de portal a GET /v3/webhooks/portal amb una clau d’API que tingui webhooks:write, recupera el secret de signatura d’aquest endpoint i emmagatzema’l per separat de la teva clau d’API en un gestor de secrets. La URL del portal dona accés per si sola i caduca al cap d’una hora, així que sol·licita’n una de nova cada vegada i no la desis ni la comparteixis. El portal agrupa els esdeveniments v3 per recurs: Customers, Capabilities, Accounts, Recipients, Transfers i API. Cada esdeveniment mostra el seu esquema de càrrega útil i un exemple. Els esdeveniments heretats es marquen com a obsolets i es llisten en un grup Legacy separat. Si el teu endpoint ja està subscrit a un esdeveniment heretat, el continua rebent. Tria noms d’esdeveniments v3 per a les subscripcions noves.

Canvia els esdeveniments d’un endpoint

Llegeix un endpoint amb GET /v3/webhooks/{webhookId}. La resposta té la mateixa forma de events que GET /v3/webhooks. Mai no inclou el secret de signatura. Les lectures requereixen webhooks:read i retornen 404 not_found per a un ID d’endpoint desconegut. Actualitza l’endpoint amb PATCH /v3/webhooks/{webhookId}. Envia una capçalera Idempotency-Key. Les actualitzacions requereixen webhooks:write.

Envia només events per conservar l’URL actual.
Envia només url per conservar la selecció d’esdeveniments actual.
events substitueix tota la selecció. Llegeix primer l’endpoint i inclou-hi tots els esdeveniments que encara necessitis.
Les subscripcions noves han d’utilitzar noms d’esdeveniments v3.
Pots conservar un nom d’esdeveniment heretat si l’endpoint ja hi està subscrit. Afegir un nom heretat nou retorna 400 validation_error.

Aquest cos conserva l’URL i substitueix la selecció:

Request body

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

Verifica abans d’analitzar

Swipelux lliura les noves integracions de webhooks a través de Svix. Verifica el cos brut de la sol·licitud amb el secret de signatura del teu endpoint i aquestes capçaleres:

svix-id
svix-timestamp
svix-signature

No analitzis el JSON ni provoquis efectes secundaris abans que la verificació tingui èxit.

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 });
}

Rebutja les sol·licituds amb signatures absents o no vàlides. Manté el cos brut disponible fins que la verificació es completi.

Persisteix, reconeix, i després processa

Posa una restricció d’unicitat sobre l’id de l’envolupant. Persisteix l’envolupant verificat, retorna 2xx ràpidament i després processa’l de manera asíncrona. Si l’ID de l’esdeveniment ja existeix, reconeix el lliurament sense repetir els efectes secundaris ja completats. Reprèn el treball local pendent o fallit mitjançant la teva pròpia cua de reintents. No utilitzis el camp attempt de l’envolupant com a clau de deduplicació o comptador de reintents de transport.

Torna a obtenir l’estat actual

L’ordre dels webhooks no és un historial autoritatiu del recurs. Utilitza resource.type i resource.id per localitzar l’objecte, i després obté el seu estat actual abans d’actualitzar el teu sistema. Per a un esdeveniment de transferència, crida GET /v3/transfers/{transferId}:

Refetch transfer

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

Impulsa l’estat visible per al client i les accions posteriors a partir de la resposta actual de l’API. Dissenya els efectes secundaris perquè siguin segurs si dos treballadors processen esdeveniments relacionats en un ordre diferent.

Recupera lliuraments

Utilitza GET /v3/webhooks/portal per obrir registres de lliurament. Amb webhooks:write, també pots reintentar lliuraments fallits o iniciar una repetició manual. Una clau amb només webhooks:read obre un portal que mostra els lliuraments, però no pot reintentar-los, repetir-los ni revelar els secrets de signatura. Cada repetició ha de passar per la mateixa verificació de signatura i safata d’entrada durable. Per recuperar-te després d’una inactivitat, repeteix la finestra afectada i torna a obtenir cada recurs referenciat. Els IDs d’esdeveniments completats romanen com a no-ops; els registres incomplets es reprenen de manera asíncrona. A continuació, verifica els lliuraments duplicats i fora d’ordre al sandbox, i després completa la llista de comprovació Anar en producció.

Comença aquí

Incorpora clients

Construeix fluxos de diners

Llança

Registra només els esdeveniments que necessites

Canvia els esdeveniments d’un endpoint

Verifica abans d’analitzar

Persisteix, reconeix, i després processa

Torna a obtenir l’estat actual

Recupera lliuraments

​Registra només els esdeveniments que necessites

​Canvia els esdeveniments d’un endpoint

​Verifica abans d’analitzar

​Persisteix, reconeix, i després processa

​Torna a obtenir l’estat actual

​Recupera lliuraments

Registra només els esdeveniments que necessites

Canvia els esdeveniments d’un endpoint

Verifica abans d’analitzar

Persisteix, reconeix, i després processa

Torna a obtenir l’estat actual

Recupera lliuraments