Configure status updates

Configure Status Updates

Purpose: Set up webhooks to receive real-time notifications when events happen.

Webhooks provide instant notifications when important events occur like transfer completions or customer updates. Instead of repeatedly checking our API, webhooks notify your application immediately when something changes.

Interactive Webhook Builder

Response Example

{
  "id": "wh_abc123def456",
  "url": "https://your-app.com/webhooks/swipelux",
  "events": [
    "customer.created",
    "transfer.completed",
    "transfer.failed"
  ],
  "secret": "whsec_abc123def456..."
}

Receiving Webhooks

Once configured, Swipelux will send HTTP POST requests to your webhook URL whenever subscribed events occur. Your endpoint should:

1. Return 200 status - Respond with a 2xx status code to acknowledge receipt
2. Process quickly - Webhook timeouts occur after 10 seconds
3. Handle idempotency - Use the idempotency_key to prevent duplicate processing

Webhook Payload Structure

Each webhook request contains a JSON payload with event details:

{
  "id": "evt_abc123def456",
  "type": "transfer.completed",
  "created": "2024-01-15T10:30:00Z",
  "idempotency_key": "idem_xyz789abc123",
  "data": {
    "object": {
      "id": "txn_def456ghi789",
      "status": "completed",
      "amount": "100.00",
      "currency": "USD",
      "customer_id": "cus_abc123def456",
      "wallet_id": "wal_ghi789jkl012"
    }
  }
}

Event Types

Validating Webhooks

Critical: Always verify webhook authenticity using the provided signature to prevent malicious requests.

Signature Verification

Each webhook includes a X-Swipelux-Signature header containing the HMAC-SHA256 signature:

X-Swipelux-Signature: t=1642248600,v1=5d41402abc4b2a76b9719d911017c592

Verification Steps

1. Extract timestamp and signature from the header
2. Prepare signed payload by concatenating timestamp + raw request body
3. Compute HMAC-SHA256 using your webhook secret
4. Compare signatures using constant-time comparison

Implementation Examples

Best Practices

• Store secrets securely - Never hardcode webhook secrets in your application
• Validate timestamps - Reject webhooks older than 5 minutes to prevent replay attacks
• Handle duplicates - Use idempotency_key to ensure events are processed only once
• Log events - Keep detailed logs for debugging and audit trails
• Graceful failures - Return appropriate error codes for temporary vs permanent failures

Troubleshooting

Common Issues

Testing Webhooks

During development, use tools like ngrok to expose your local server:

ngrok http 3000
# Use the generated URL: https://abc123.ngrok.io/webhooks/swipelux

Next Steps: With webhooks configured, you have real-time visibility into all customer and transfer events. This completes the core integration flow!