Webhooks

For complete API specification, see the API Reference.

Monitor balance changes and transfer status in real-time using webhooks.

Configure Webhooks

Set up webhook notifications to receive instant updates when events occur.

curl -X PATCH https://api.swipelux.com/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhooks"}'

Webhook Payload Structure

All webhook events follow this structure:

{
  "type": "event.type",
  "data": { ... },
  "createdAt": 1705312200000
}

Customer Events

customer.created

Triggered when a new individual customer is created.

{
  "type": "customer.created",
  "data": {
    "id": "cus_abc123",
    "email": "john@example.com",
    "firstName": "John",
    "middleName": null,
    "lastName": "Doe",
    "birthDate": "1990-01-15T00:00:00.000Z",
    "phone": "+1234567890"
  },
  "createdAt": 1705312200000
}

customer.updated

Triggered when customer data is updated.

{
  "type": "customer.updated",
  "data": {
    "id": "cus_abc123",
    "email": "john.updated@example.com",
    "firstName": "John",
    "middleName": null,
    "lastName": "Doe",
    "phone": "+1234567890"
  },
  "createdAt": 1705312200000
}

customer.verification_changed

Triggered when a customer's KYC/KYB verification status changes.

{
  "type": "customer.verification_changed",
  "data": {
    "customerId": "cus_abc123",
    "customerType": "individual",
    "verificationStatus": "approved",
    "previousStatus": "pending",
    "reason": null
  },
  "createdAt": 1705312200000
}

Field	Type	Description
`customerId`	string	Customer ID
`customerType`	string	`individual` or `business`
`verificationStatus`	string	`not_started`, `pending`, `approved`, or `rejected`
`previousStatus`	string	Previous status before this change
`reason`	string	Rejection reason (only when rejected)

Business Customer Events

business.created

Triggered when a new business customer is created.

{
  "type": "business.created",
  "data": {
    "id": "cus_abc123",
    "entityName": "Acme Corporation",
    "email": "contact@acme.com",
    "type": "business"
  },
  "createdAt": 1705312200000
}

business.updated

Triggered when business customer data is updated.

{
  "type": "business.updated",
  "data": {
    "id": "cus_abc123",
    "entityName": "Acme Corporation",
    "email": "contact@acme.com"
  },
  "createdAt": 1705312200000
}

Wallet Events

wallet.created

Triggered when a new custodial wallet is created for a customer.

{
  "type": "wallet.created",
  "data": {
    "id": "wal_xyz789",
    "customerId": "cus_abc123",
    "chain": "polygon",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "createdAt": 1705312200000
}

wallet.imported

Triggered when an external wallet is imported for tracking.

{
  "type": "wallet.imported",
  "data": {
    "id": "wal_xyz789",
    "customerId": "cus_abc123",
    "chain": "ethereum",
    "address": "0xabcdef1234567890abcdef1234567890abcdef12"
  },
  "createdAt": 1705312200000
}

Document Events

document.uploaded

Triggered when a document is uploaded for a customer or shareholder.

{
  "type": "document.uploaded",
  "data": {
    "id": "bizdoc_xyz789",
    "customerId": "cus_abc123",
    "type": "certificate_of_incorporation",
    "status": "pending"
  },
  "createdAt": 1705312200000
}

Field	Type	Description
`id`	string	Document ID (`bizdoc_xxx` for business, `shdoc_xxx` for shareholder)
`customerId`	string	Customer ID
`type`	string	Document type (e.g., `certificate_of_incorporation`, `passport_front`)
`status`	string	`pending`, `approved`, or `rejected`

Account Events

account.created

Triggered when a virtual bank account (vIBAN) is created.

{
  "type": "account.created",
  "data": {
    "id": "acc_def456",
    "customerId": "cus_abc123",
    "type": "sepa",
    "source": "virtual",
    "currency": "EUR",
    "country": "DE"
  },
  "createdAt": 1705312200000
}

account.imported

Triggered when an external bank account is imported for payouts.

{
  "type": "account.imported",
  "data": {
    "id": "acc_def456",
    "customerId": "cus_abc123",
    "type": "sepa",
    "source": "external",
    "currency": "EUR",
    "country": "DE"
  },
  "createdAt": 1705312200000
}

account.deleted

Triggered when a bank account is deleted.

{
  "type": "account.deleted",
  "data": {
    "id": "acc_def456",
    "customerId": "cus_abc123",
    "type": "sepa"
  },
  "createdAt": 1705312200000
}

Transfer Events

transfer.created

Triggered when a new transfer (payin or payout) is initiated.

{
  "type": "transfer.created",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "state": "pending"
  },
  "createdAt": 1705312200000
}

transfer.updated

Triggered when a transfer status changes.

{
  "type": "transfer.updated",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "state": "processing"
  },
  "createdAt": 1705312200000
}

transfer.completed

Triggered when a transfer completes successfully.

{
  "type": "transfer.completed",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "state": "completed"
  },
  "createdAt": 1705312200000
}

transfer.failed

Triggered when a transfer fails.

{
  "type": "transfer.failed",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "state": "failed"
  },
  "createdAt": 1705312200000
}

transfer.funded_partial

Triggered when a transfer receives partial funding.

{
  "type": "transfer.funded_partial",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "state": "funded_partial"
  },
  "createdAt": 1705312200000
}

transfer.amount_adjusted

Triggered when a transfer amount is adjusted (e.g., due to fees or exchange rate).

{
  "type": "transfer.amount_adjusted",
  "data": {
    "id": "tr_xyz789",
    "onBehalfOf": "cus_abc123",
    "from": "100.00",
    "to": "95.50"
  },
  "createdAt": 1705312200000
}

Event Types Reference

Event	Description
`customer.created`	New individual customer created
`customer.updated`	Customer data updated
`customer.verification_changed`	KYC status changed
`business.created`	New business customer created
`business.updated`	Business customer data updated
`wallet.created`	Custodial wallet created
`wallet.imported`	External wallet imported
`document.uploaded`	Document uploaded for customer/shareholder
`account.created`	Virtual bank account created
`account.imported`	External bank account imported
`account.deleted`	Bank account deleted
`transfer.created`	Transfer initiated
`transfer.updated`	Transfer status changed
`transfer.completed`	Transfer completed
`transfer.failed`	Transfer failed
`transfer.funded_partial`	Partial funding received
`transfer.amount_adjusted`	Transfer amount adjusted

Webhook Security

Webhooks are signed using HMAC-SHA256. Verify signatures using the X-Webhook-Signature header:

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

On this page