Webhooks

Before You Start

Read the following guides before proceeding:

Overview

Wirex delivers HTTP POST notifications to the webhook base URL registered for your company. The same
dispatcher serves retail and corporate companies, so the delivery contract and the payload shapes are
shared across both APIs — only the set of entities you receive differs.

Delivery Model

• Method: HTTP POST with a JSON body
• Content-Type: application/json
• Timeout: 10 seconds per request
• Retries: Failed deliveries are logged and not retried
• Authentication: No authentication headers are added to webhook requests

Validate webhook origin at the network level (IP allowlisting) and implement idempotent handlers —
a delivery can repeat.

There is no per-corporation webhook URL. Every corporation registered under your partner_id delivers
to the same base URL; use corporation_address in the payload to route.

Endpoints

/v2/webhooks/user and /v2/webhooks/debt-cases carry retail user entities and are not delivered for
corporations.

Corporation Webhook

Endpoint: POST {your_webhook_base_url}/v2/webhooks/corporations

Delivered when the corporation record changes — most importantly when KYB moves through
Applied → InReview → Approved, and when the profile becomes Active.

{
  "corporation_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "owner_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "corporation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "corporation_name": "Acme Inc",
  "corporation_type": "LimitedLiability",
  "verification_status": "Approved",
  "status": "Active",
  "registration_number": "12345678",
  "corporation_registration_address": {
    "line1": "10 Downing Street",
    "line2": "Flat 2",
    "city": "London",
    "state": "",
    "country": "GB",
    "postal_code": "SW1A 2AA"
  },
  "corporation_contact_details": {
    "name": "Alex Grey",
    "email": "[email protected]",
    "phone_number": "+447700900123"
  },
  "freshdesk_id": "1234567890"
}

The corporation webhook carries a narrower payload than GET /api/v1/corporations. It has no
capabilities, no actions and no verification_levels. Treat it as a signal to re-read the
corporation, not as a replacement for reading it — capability transitions are only visible on the read
endpoint.

Shared Payloads

The wallet, balance, card, card-limit, 3DS, activity, recipient and ERC-withdrawal payloads are produced
by the shared dispatcher and are documented in the retail Webhooks guide. They arrive
unchanged for corporations.

Two differences matter when you map them onto Corporate API responses:

• The card webhook is the retail card shape. It carries generation and balances, and its limit
  object carries lifetime_limit and lifetime_usage — none of which appear in
  GET /api/v1/cards. Ignore the extra fields rather than modelling your card record on the webhook.
• Wallet and balance events are addressed by wallet address, not corporation id. Resolve the
  corporation by matching wallet_address against GET /api/v1/wallets.

What Is Not Delivered

There is no webhook for employees, roles, bank account activation, FX swaps or bulk transfer approval.
Poll the corresponding endpoint after the call that started the work: