Webhooks

Use webhooks to react to asynchronous changes. Delivery is at least once, so duplicate, delayed, and out-of-order events are normal.

Register only the events you need

Create an endpoint with POST /v3/webhooks. Subscribe only to documented events that drive your integration. This example uses 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

Store response data.id as WEBHOOK_ID. Request a portal URL from GET /v3/webhooks/portal with an API key that has webhooks:write, retrieve this endpoint’s signing secret, and store it separately from your API key in a secret manager. The portal URL grants access on its own and expires after one hour, so request a new one each time and do not store or share it. The portal groups v3 events by resource: Customers, Capabilities, Accounts, Recipients, Transfers, and API. Each event shows its payload schema and an example. Legacy events are marked deprecated and listed in a separate Legacy group. If your endpoint already subscribes to a legacy event, it keeps receiving it. Choose v3 event names for new subscriptions.

Change an endpoint’s events

Read one endpoint with GET /v3/webhooks/{webhookId}. The response has the same events shape as GET /v3/webhooks. It never includes the signing secret. Reads require webhooks:read and return 404 not_found for an unknown endpoint ID. Update the endpoint with PATCH /v3/webhooks/{webhookId}. Send an Idempotency-Key header. Updates require webhooks:write.

Send only events to keep the current URL.
Send only url to keep the current event selection.
events replaces the whole selection. Read the endpoint first and include every event you still need.
New subscriptions must use v3 event names.
You can keep a legacy event name if the endpoint already subscribes to it. Adding a new legacy name returns 400 validation_error.

Until your integrating business KYB is approved, you can make 20 webhook URL changes per hour in total, across all endpoints in your live spaces that require KYB. Changes in sandbox spaces do not count. Creating an endpoint or changing its url counts as a change. Changing only events or saving the current URL does not. Exceeding the limit returns 422 merchant_kyb_not_approved. See Go live. This body keeps the URL and replaces the selection:

Request body

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

Verify before parsing

Swipelux delivers new webhook integrations through Svix. Verify the raw request body with your endpoint signing secret and these headers:

svix-id
svix-timestamp
svix-signature

Do not parse JSON or cause side effects before verification succeeds.

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

Reject requests with missing or invalid signatures. Keep the raw body available until verification completes.

Persist, acknowledge, then process

Put a uniqueness constraint on the envelope id. Persist the verified envelope, return 2xx promptly, then process it asynchronously. If the event ID already exists, acknowledge the delivery without repeating completed side effects. Resume pending or failed local work through your own retry queue. Do not use the envelope attempt field as a deduplication key or transport retry counter.

Refetch current state

Webhook order is not an authoritative resource history. Use resource.type and resource.id to locate the object, then fetch its current state before updating your system. For a transfer event, call GET /v3/transfers/{transferId}:

Refetch transfer

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

Drive customer-visible status and downstream actions from the current API response. Design side effects to remain safe if two workers process related events in a different order.

Recover deliveries

Use GET /v3/webhooks/portal to open delivery logs. With webhooks:write, you can also retry failed deliveries or start a manual replay. A key with only webhooks:read opens a portal that shows deliveries but cannot retry them, replay them, or reveal signing secrets. Every replay must pass through the same signature verification and durable inbox. To recover after downtime, replay the affected window and refetch each referenced resource. Completed event IDs remain no-ops; incomplete records resume asynchronously. Next, verify duplicate and out-of-order deliveries in sandbox, then complete the Go live checklist.

Get started

Onboard customers

Build money flows

Launch

Register only the events you need

Change an endpoint’s events

Verify before parsing

Persist, acknowledge, then process

Refetch current state

Recover deliveries

​Register only the events you need

​Change an endpoint’s events

​Verify before parsing

​Persist, acknowledge, then process

​Refetch current state

​Recover deliveries

Register only the events you need

Change an endpoint’s events

Verify before parsing

Persist, acknowledge, then process

Refetch current state

Recover deliveries