Wirex Baas Webhooks

Wirex BaaS Webhooks & Activity History

Wirex BaaS uses webhooks to notify partners of state changes in real time. This skill covers all webhook endpoints (v2 and v1 legacy), delivery semantics, payload structures, and the activity history feed API.

Webhook Delivery Semantics

Security: Since no authentication headers are included, implement network-level controls such as IP allowlisting or payload verification to secure your webhook endpoints.

Your webhook receiver must:

1. Return a 2xx HTTP status within 10 seconds.
2. Implement idempotent handlers -- the same event may be delivered more than once in edge cases.
3. Offload heavy processing to an async queue -- do not block the response while processing business logic.

If the receiver does not respond with 2xx within the timeout window, the delivery is recorded as failed and will not be retried. Monitor your webhook logs and implement a polling fallback using the activity history feed for critical flows.

V2 Webhook Endpoints

All v2 webhooks are delivered to partner-registered URLs. The path suffixes below indicate the event category.

V1 Legacy Webhook Endpoints

These endpoints are maintained for backward compatibility with earlier integrations.

Activity Types

The activity system categorizes all financial operations. Each activity has a type, status, direction, and a sequence of activity_steps.

Activity Type Values

Activity Status Values

Activity Direction Values

Activity Step Types

Each activity progresses through a sequence of steps. The activity_steps array tracks each step's type, status, and timestamps.

Implementation Best Practices

WARNING: Failed webhook deliveries are logged but NOT retried. Implement polling fallback for critical flows.

Webhook handling flow:

1. Receive POST → validate payload → return 200 OK immediately (within 10 seconds)
2. Enqueue payload for async processing (SQS, RabbitMQ, Redis Streams)
3. Process idempotently — use the activity id or unique event identifier to deduplicate
4. Log every received webhook (timestamp, endpoint, payload hash) for debugging
5. Poll the activity history feed (GET /api/v1/activity/feed) as fallback for missed webhooks

Activity History Feed

The activity history endpoint provides a paginated, filterable feed of all user activities. Use it as a fallback for missed webhooks or for building transaction history UIs.

GET /api/v1/activity/feed

Headers:

Query Parameters:

Important: The types and subject parameters are mutually exclusive. You cannot use both in the same request.

Subject Types

The subject parameter accepts identifiers for specific entity types:

Response Structure

The response wraps activities in a pagination envelope:

{
  "activities": [
    {
      "id": "act_abc123",
      "user_address": "0x...",
      "type": "CardTransaction",
      "status": "Completed",
      "direction": "Outbound",
      "source": {
        "type": "Cards",
        "card_id": "card-uuid"
      },
      "destination": {
        "type": "Merchant",
        "merchant_name": "Amazon"
      },
      "source_amount": {
        "amount": "25.50",
        "token_symbol": "WUSD",
        "token_address": "0xb4bB2032A73A53C0Aa7Dc9ee2d9658a978fA7bC2"
      },
      "destination_amount": {
        "amount": "25.50",
        "token_symbol": "WUSD",
        "token_address": "0xb4bB2032A73A53C0Aa7Dc9ee2d9658a978fA7bC2"
      },
      "rate": {
        "ticker": "EUR/WEUR",
        "rate": 1.0
      },
      "activity_steps": [
        {
          "type": "Initiated",
          "status": "Completed",
          "created_at": "2025-03-15T10:30:00Z",
          "completed_at": "2025-03-15T10:30:00Z"
        },
        {
          "type": "CardOut",
          "status": "Completed",
          "created_at": "2025-03-15T10:30:01Z",
          "completed_at": "2025-03-15T10:30:02Z"
        },
        {
          "type": "Completed",
          "status": "Completed",
          "created_at": "2025-03-15T10:30:02Z",
          "completed_at": "2025-03-15T10:30:02Z"
        }
      ],
      "created_at": "2025-03-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page_number": 1,
    "page_size": 25,
    "total_count": 142
  }
}

Filter Examples

Fetch all SEPA activities:

GET /api/v1/activity/feed?types=Sepa&page_number=1&page_size=50

Fetch activities for a specific card:

GET /api/v1/activity/feed?subject=card-uuid&page_number=1&page_size=25

Fetch crypto and exchange activities:

GET /api/v1/activity/feed?types=Crypto,Exchange&page_number=1&page_size=25

Error Responses

The activity history endpoint returns structured errors for invalid requests:

Error response body:

{
  "error_reason": "ErrorInvalidField",
  "error_description": "The types and subject parameters are mutually exclusive",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "issue", "details": "mutually_exclusive" }
  ]
}

See references/REFERENCE.md for complete webhook payload examples for every endpoint.