Webhooks

Bruk webhooks til å reagere på asynkrone endringer. Levering skjer minst én gang, så duplikater, forsinkede og hendelser i feil rekkefølge er normalt.

Registrer kun hendelsene du trenger

Opprett et endepunkt med POST /v3/webhooks. Abonner kun på dokumenterte hendelser som driver integrasjonen din. Dette eksempelet bruker 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

Lagre respons data.id som WEBHOOK_ID. Be om en portal-URL fra GET /v3/webhooks/portal med en API-nøkkel som har webhooks:write, hent dette endepunktets signeringshemmelighet, og oppbevar den separat fra API-nøkkelen din i en hemmelighetshåndterer. Portal-URL-en gir tilgang på egen hånd og utløper etter én time, så be om en ny hver gang, og ikke lagre eller del den. Portalen grupperer v3-hendelser etter ressurs: Customers, Capabilities, Accounts, Recipients, Transfers og API. Hver hendelse viser payload-skjemaet sitt og et eksempel. Eldre hendelser er merket som utfasede og oppført i en egen Legacy-gruppe. Hvis endepunktet ditt allerede abonnerer på en eldre hendelse, fortsetter det å motta den. Velg v3-hendelsesnavn for nye abonnementer.

Endre hendelsene til et endepunkt

Les ett endepunkt med GET /v3/webhooks/{webhookId}. Responsen har samme events-struktur som GET /v3/webhooks. Den inkluderer aldri signeringshemmeligheten. Lesing krever webhooks:read og returnerer 404 not_found for en ukjent endepunkt-ID. Oppdater endepunktet med PATCH /v3/webhooks/{webhookId}. Send en Idempotency-Key-header. Oppdateringer krever webhooks:write.

Send kun events for å beholde gjeldende URL.
Send kun url for å beholde gjeldende utvalg av hendelser.
events erstatter hele utvalget. Les endepunktet først og ta med alle hendelser du fortsatt trenger.
Nye abonnementer må bruke v3-hendelsesnavn.
Du kan beholde et eldre hendelsesnavn hvis endepunktet allerede abonnerer på det. Å legge til et nytt eldre navn returnerer 400 validation_error.

Denne body-en beholder URL-en og erstatter utvalget:

Request body

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

Verifiser før parsing

Swipelux leverer nye webhook-integrasjoner via Svix. Verifiser den rå forespørsel-body-en med endepunktets signeringshemmelighet og disse headerne:

svix-id
svix-timestamp
svix-signature

Ikke parse JSON eller forårsak sideeffekter før verifiseringen lykkes.

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

Avvis forespørsler med manglende eller ugyldige signaturer. Behold den rå body-en tilgjengelig til verifiseringen er ferdig.

Persister, bekreft og prosesser

Legg en unikhetsbegrensning på konvoluttens id. Persister den verifiserte konvolutten, returner 2xx raskt, og prosesser den så asynkront. Hvis hendelses-ID-en allerede finnes, bekreft leveransen uten å gjenta fullførte sideeffekter. Gjenoppta ventende eller feilende lokalt arbeid via din egen retry-kø. Ikke bruk konvoluttens attempt-felt som dedupliseringsnøkkel eller transporttelleverdi for retries.

Hent gjeldende tilstand på nytt

Webhook-rekkefølgen er ikke en autoritativ ressurshistorikk. Bruk resource.type og resource.id for å finne objektet, og hent så gjeldende tilstand før du oppdaterer systemet ditt. For en overføringshendelse, kall GET /v3/transfers/{transferId}:

Refetch transfer

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

Driv kundevisibel status og etterfølgende handlinger fra gjeldende API-respons. Design sideeffekter slik at de forblir trygge hvis to arbeidere prosesserer relaterte hendelser i en annen rekkefølge.

Gjenopprett leveranser

Bruk GET /v3/webhooks/portal for å åpne leveranselogger. Med webhooks:write kan du også prøve mislykkede leveranser på nytt eller starte en manuell avspilling. En nøkkel med bare webhooks:read åpner en portal som viser leveranser, men som ikke kan prøve dem på nytt, spille dem av på nytt eller vise signeringshemmeligheter. Hver avspilling må passere gjennom samme signaturverifisering og holdbare inbox. For å gjenopprette etter nedetid, spill av det berørte vinduet på nytt og hent hver refererte ressurs på nytt. Fullførte hendelses-ID-er forblir no-ops; ufullstendige oppføringer gjenopptas asynkront. Deretter, verifiser dupliserte og feilaktig rekkefølge-leveranser i sandbox, og fullfør så sjekklisten for Go live.

Kom i gang

Kundeombording

Bygg pengestrømmer

Lansering

Registrer kun hendelsene du trenger

Endre hendelsene til et endepunkt

Verifiser før parsing

Persister, bekreft og prosesser

Hent gjeldende tilstand på nytt

Gjenopprett leveranser

​Registrer kun hendelsene du trenger

​Endre hendelsene til et endepunkt

​Verifiser før parsing

​Persister, bekreft og prosesser

​Hent gjeldende tilstand på nytt

​Gjenopprett leveranser

Registrer kun hendelsene du trenger

Endre hendelsene til et endepunkt

Verifiser før parsing

Persister, bekreft og prosesser

Hent gjeldende tilstand på nytt

Gjenopprett leveranser