Webhooks

Webhooks notify your platform when customer, verification, rail, and transfer states change asynchronously. Use them to update internal state without polling every object.

Swipelux delivers webhooks through Svix. Svix delivery and signature verification are the public integration contract.

Supported Events

Delivery Shape

{
  "type": "transfer.completed",
  "data": {
    "id": "tr_xxx",
    "onBehalfOf": "cus_xxx",
    "state": "completed"
  },
  "createdAt": 1704067200000
}

createdAt is a Unix timestamp in milliseconds.

Webhook deliveries use a JSON event body. The payload examples on this page show the body your endpoint receives; do not Base64-decode the webhook body before parsing it.

Correlate Webhooks To API Requests

Core API pay-in, payout, and transfer webhooks are correlated by Swipelux object IDs, not by a merchant-supplied externalId.

When you create a pay-in or payout, store the returned id from the response. That value is the transfer ID (tr_xxx) used in transfer.*, payin.*, and payout.* webhook payloads. If you execute the flow from a quote, also store the quote ID (quo_xxx): GET /v1/transfers/{id} accepts either the transfer ID or the consumed quote ID and returns the transfer.

Legacy widget order identifiers are separate from the public Core API webhook contract. Do not expect a legacy widget externalId to appear in Core API pay-in or transfer webhook payloads unless that field is documented in the API reference for the endpoint you are using.

Customer Lifecycle

customer.created and customer.updated include the merchant-visible customer fields returned by the customer API.

{
  "type": "customer.created",
  "data": {
    "id": "cus_abc123",
    "type": "individual",
    "status": "not_started",
    "createdAt": "2026-05-18T10:00:00.000Z",
    "updatedAt": "2026-05-18T10:00:00.000Z",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phone": "+15551234567",
    "country": "US"
  },
  "createdAt": 1704067200000
}

{
  "type": "customer.updated",
  "data": {
    "id": "cus_abc123",
    "type": "individual",
    "status": "not_started",
    "createdAt": "2026-05-18T10:00:00.000Z",
    "updatedAt": "2026-05-18T11:00:00.000Z",
    "firstName": "Ada",
    "lastName": "Byron",
    "email": "ada@example.com",
    "phone": "+15551234567",
    "country": "US"
  },
  "createdAt": 1704067200000
}

Partial Funding

transfer.funded_partial uses the completed transfer state and reports both the expected amount and the received amount. fromAmount equals the received amount.

{
  "type": "transfer.funded_partial",
  "data": {
    "id": "tr_xxx",
    "onBehalfOf": "cus_xxx",
    "state": "completed",
    "expectedAmount": "100.00",
    "receivedAmount": "75.00",
    "fromAmount": "75.00"
  },
  "createdAt": 1704067200000
}

Transfer Completion Amounts

transfer.created, transfer.updated, transfer.completed, and transfer.failed are compatibility lifecycle events for pay-ins, payouts, and transfers. They include fromAmount; toAmount is included when Swipelux has a positive destination amount.

For card pay-ins, transfer.completed.toAmount is the delivered amount when that amount is known.

{
  "type": "transfer.completed",
  "data": {
    "id": "tr_xxx",
    "onBehalfOf": "cus_xxx",
    "state": "completed",
    "fromAmount": "100.00",
    "toAmount": "100.00"
  },
  "createdAt": 1704067200000
}

Pay-in And Payout Events

For API-created pay-ins and payouts, payin.* and payout.* events are emitted additively with transfer.* compatibility events. Pay-in payloads follow the pay-in API response shape. Payout payloads follow the payout API response shape.

{
  "type": "payin.completed",
  "data": {
    "id": "tr_xxx",
    "to": "wal_xxx",
    "rail": "ach",
    "currency": "USD",
    "amount": "100.00",
    "state": "completed"
  },
  "createdAt": 1704067200000
}

Virtual-account deposits emit transfer lifecycle events after Swipelux attributes the incoming funds to the customer and destination wallet. Completed attributed deposits also emit payin.completed. Unresolved provider-side evidence does not emit merchant lifecycle webhooks until it is tied to an existing pay-in or resolved into a completed pay-in transfer.

Rail Status

Rail status events identify the qualified rail.

{
  "type": "customer.rail.status_changed",
  "data": {
    "customerId": "cus_xxx",
    "rail": "ach_named",
    "railStatus": "ready_to_use"
  },
  "createdAt": 1704067200000
}

Rail Documents Requested

Document request events also identify the qualified rail.

{
  "type": "customer.rail.documents_requested",
  "data": {
    "customerId": "cus_xxx",
    "rail": "ach_named",
    "requiredDocuments": ["bank_statement"],
    "reason": "Compliance requires an updated bank statement"
  },
  "createdAt": 1704067200000
}

Verify Deliveries

Verify each delivery with the Svix headers on the HTTP request:

• svix-id
• svix-timestamp
• svix-signature

Legacy HMAC fields such as secretKey may remain visible in compatibility responses, but do not treat HMAC-SHA256 or X-Webhook-Signature as the primary verification path for new integrations.

Configure Delivery

PATCH /v1/webhooks configures the delivery URL. It does not accept an events array and does not mutate the subscribed event list. New endpoints are subscribed to the supported public event catalog; per-endpoint event filters are managed in Svix.

When an endpoint has a narrow Svix-managed event filter, Swipelux keeps customer.verification_changed included so verification lifecycle changes continue to deliver.

API Reference