Webhook

Usa i webhook per reagire ai cambiamenti asincroni. La consegna è at-least-once, quindi eventi duplicati, in ritardo e fuori ordine sono normali.

Registra solo gli eventi di cui hai bisogno

Crea un endpoint con POST /v3/webhooks. Iscriviti solo agli eventi documentati che guidano la tua integrazione. Questo esempio usa 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

Salva il data.id della risposta come WEBHOOK_ID. Richiedi un URL del portale a GET /v3/webhooks/portal con una chiave API che ha webhooks:write, recupera il signing secret di questo endpoint e conservalo separatamente dalla chiave API in un secret manager. L’URL del portale concede l’accesso da solo e scade dopo un’ora, quindi richiedine uno nuovo ogni volta e non salvarlo né condividerlo. Il portale raggruppa gli eventi v3 per risorsa: Customers, Capabilities, Accounts, Recipients, Transfers e API. Ogni evento mostra il proprio schema di payload e un esempio. Gli eventi legacy sono contrassegnati come deprecati ed elencati in un gruppo Legacy separato. Se il tuo endpoint è già iscritto a un evento legacy, continua a riceverlo. Scegli nomi di evento v3 per le nuove iscrizioni.

Modifica gli eventi di un endpoint

Leggi un endpoint con GET /v3/webhooks/{webhookId}. La risposta ha la stessa struttura events di GET /v3/webhooks. Non include mai il signing secret. Le letture richiedono webhooks:read e restituiscono 404 not_found per un ID endpoint sconosciuto. Aggiorna l’endpoint con PATCH /v3/webhooks/{webhookId}. Invia un header Idempotency-Key. Gli aggiornamenti richiedono webhooks:write.

Invia solo events per mantenere l’URL corrente.
Invia solo url per mantenere la selezione di eventi corrente.
events sostituisce l’intera selezione. Leggi prima l’endpoint e includi ogni evento di cui hai ancora bisogno.
Le nuove iscrizioni devono usare nomi di evento v3.
Puoi mantenere un nome di evento legacy se l’endpoint è già iscritto a quell’evento. L’aggiunta di un nuovo nome legacy restituisce 400 validation_error.

Questo body mantiene l’URL e sostituisce la selezione:

Request body

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

Verifica prima di parsare

Swipelux consegna le nuove integrazioni webhook tramite Svix. Verifica il body grezzo della richiesta con il signing secret dell’endpoint e questi header:

svix-id
svix-timestamp
svix-signature

Non parsare JSON o causare side effect prima che la verifica abbia successo.

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

Rifiuta le richieste con firme mancanti o non valide. Mantieni disponibile il body grezzo finché la verifica non è completa.

Persisti, conferma e poi processa

Imposta un vincolo di univocità sull’id dell’envelope. Persisti l’envelope verificato, restituisci 2xx prontamente, poi processalo in modo asincrono. Se l’ID evento esiste già, conferma la consegna senza ripetere side effect già completati. Riprendi il lavoro locale pending o fallito tramite la tua coda di retry. Non usare il campo attempt dell’envelope come chiave di deduplicazione o come contatore di retry di trasporto.

Rileggi lo stato corrente

L’ordine dei webhook non è una cronologia autorevole della risorsa. Usa resource.type e resource.id per localizzare l’oggetto, poi recupera il suo stato corrente prima di aggiornare il tuo sistema. Per un evento di transfer, chiama GET /v3/transfers/{transferId}:

Refetch transfer

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

Guida lo stato visibile al cliente e le azioni downstream dalla risposta API corrente. Progetta i side effect in modo che restino sicuri se due worker processano eventi correlati in ordine diverso.

Recupera le consegne

Usa GET /v3/webhooks/portal per aprire i log di consegna. Con webhooks:write puoi anche ritentare le consegne fallite o avviare un replay manuale. Una chiave con il solo webhooks:read apre un portale che mostra le consegne ma non può ritentarle, riprodurle né rivelare i signing secret. Ogni replay deve passare per la stessa verifica di firma e per la stessa inbox durevole. Per recuperare dopo un downtime, ripeti la finestra interessata e rileggi ogni risorsa referenziata. Gli ID evento completati restano no-op; i record incompleti riprendono in modo asincrono. Successivamente, verifica in sandbox le consegne duplicate e fuori ordine, poi completa la checklist Go live.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

Registra solo gli eventi di cui hai bisogno

Modifica gli eventi di un endpoint

Verifica prima di parsare

Persisti, conferma e poi processa

Rileggi lo stato corrente

Recupera le consegne

​Registra solo gli eventi di cui hai bisogno

​Modifica gli eventi di un endpoint

​Verifica prima di parsare

​Persisti, conferma e poi processa

​Rileggi lo stato corrente

​Recupera le consegne

Registra solo gli eventi di cui hai bisogno

Modifica gli eventi di un endpoint

Verifica prima di parsare

Persisti, conferma e poi processa

Rileggi lo stato corrente

Recupera le consegne