Skip to main content
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.
Store response data.id as WEBHOOK_ID. Open the portal returned by GET /v3/webhooks/portal, retrieve this endpoint’s signing secret, and store it separately from your API key in a secret manager.

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.
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}:
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, retry failed deliveries, or start a manual replay. 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.