TRUSTODI

Or manage endpoints over the API

All three endpoints share the same authentication as the rest of the white-label API and operate on the environment matched by your API key (sandbox vs production).

• POST /api/trustodi/v1/webhooks — register a new endpoint
• GET /api/trustodi/v1/webhooks — list your endpoints
• DELETE /api/trustodi/v1/webhooks/:webhookId — remove an endpoint

Event catalog

These are the events you can subscribe to today. Each event delivers the common envelope plus one entity object (see Sample payloads below).

Sample payloads

Every delivery wraps a common envelope around one entity object. The envelope fields are always present:

{
  "event": "customer.created",          // the event type
  "partner_id": "AFF008",              // your partner ID
  "environment": "production",           // "sandbox" or "production"
  "timestamp": "2026-06-12T07:00:00.000Z"
  // ...plus one entity object (see below)
}

These are the exact shapes you receive. Fields are omitted when they have no value, so treat every field except the "always present" ones as optional and code defensively. Identify records by the TRUSTODI id (id / account_id), never by any provider id.

customer.created — always present: id, type, kyc_status

{
  "event": "customer.created",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T07:00:00.000Z",
  "customer": {
    "id": "CUST_1700000000000",
    "external_id": "your-own-ref-123",
    "name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "type": "INDIVIDUAL",
    "kyc_status": "NOT_STARTED",
    "kyc_url": "https://app.trustodi.com/kyc/abc123"
  }
}

customer.updated — fires on KYC status changes; carries updated_at

{
  "event": "customer.updated",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T08:00:00.000Z",
  "customer": {
    "id": "CUST_1700000000000",
    "external_id": "your-own-ref-123",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "country": "US",
    "type": "INDIVIDUAL",
    "kyc_status": "APPROVED",
    "updated_at": "2026-06-12T08:00:00.000Z"
  }
}

account.created (virtual bank) — always present: account_id, customer_id, account_type, currency

{
  "event": "account.created",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T07:00:00.000Z",
  "account": {
    "account_id": "vba_1700000000000",
    "customer_id": "CUST_1700000000000",
    "account_type": "VIRTUAL_BANK",
    "currency": "EUR",
    "nickname": "EUR payouts",
    "bank_name": "Example Bank S.A.",
    "iban": "DE89370400440532013000",
    "account_number": "0532013000",
    "status": "ACTIVE",
    "is_virtual": true
  }
}

account.created (wallet) — wallets carry address + chain instead of bank fields

{
  "event": "account.created",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T07:00:00.000Z",
  "account": {
    "account_id": "wlt_1700000000000",
    "customer_id": "CUST_1700000000000",
    "account_type": "VIRTUAL_WALLET",
    "currency": "USDC",
    "chain": "SOLANA",
    "address": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2",
    "status": "ACTIVE",
    "is_virtual": true
  }
}

account.updated — carries updated_at

{
  "event": "account.updated",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T09:00:00.000Z",
  "account": {
    "account_id": "vba_1700000000000",
    "customer_id": "CUST_1700000000000",
    "account_type": "VIRTUAL_BANK",
    "currency": "EUR",
    "nickname": "EUR payouts (updated)",
    "is_primary": true,
    "updated_at": "2026-06-12T09:00:00.000Z"
  }
}

payment.created — full source/destination breakdown; always present: id, reference, type, status

{
  "event": "payment.created",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T10:00:00.000Z",
  "payment": {
    "id": "TRX-ABC123",
    "reference": "TRX-ABC123",
    "type": "onramp",
    "status": "PENDING",
    "source_currency": "USD",
    "source_amount": 100,
    "destination_currency": "USDC",
    "destination_amount": 99.5,
    "destination_account_id": "vba_1700000000000",
    "destination_rail": "SOLANA",
    "quote_id": "quote_abc123",
    "total_fees": 0.5,
    "exchange_rate": 1.0
  }
}

payment.updated — fires on every status change; carries amount + currency (and failure_reason on failure)

{
  "event": "payment.updated",
  "partner_id": "AFF008",
  "environment": "production",
  "timestamp": "2026-06-12T10:05:00.000Z",
  "payment": {
    "id": "TRX-ABC123",
    "reference": "TRX-ABC123",
    "type": "onramp",
    "status": "COMPLETED",
    "amount": 100,
    "currency": "USD"
  }
}

Verifying deliveries

Every webhook delivery is signed. When you register an endpoint, the response includes a signing secret (whsec_…) shown only once — store it securely. Each request carries signature headers:

• webhook-id — unique message ID
• webhook-timestamp — Unix send time (reject deliveries that are too old to prevent replay)
• webhook-signature — the signature to compare against the secret

Verify the signature on every request before trusting it. Our delivery is built on the open standard webhook signature scheme, and the official verification libraries (available for most languages) check the headers for you in one call — pass the raw request body and your signing secret.

Integration notes

• KYC outcomes arrive as customer.updated — there is no separate kyc.* event. Watch the kyc_status field on the customer object to track approval.
• Correlate on our customer ID (e.g. CUST_…), not the underlying provider's ID. The provider's ID can change and should not be used as your key.
• Sandbox and production are fully isolated — each environment has its own endpoints and signing secrets, and every payload carries environment so you can route accordingly.
• Delivery is at-least-once — failed deliveries are retried, so the same event may arrive more than once. Make your handlers idempotent (de-duplicate on the webhook-id header or the entity ID + status).
• Some events cannot be fully exercised in sandbox. Deposit-driven events depend on real money movement, so in sandbox you can trigger customer.*, account.created/updated and payment.created by calling the API, but a payment.updated that reaches COMPLETED — and bank details that only populate after the account is fully provisioned (e.g. iban) — require a real deposit and therefore appear in production. Build against the documented shapes above; the field set is identical across environments.