Notification examples

One payload per event, grouped by resource. Every delivery has the same envelope — event names what happened, data carries it — so the objects below are what arrives in data. Every payload carries an event_id. Use it to make your handler idempotent: record what you have already processed and ignore a repeat.

Sub-client

user.created

{
  "event_id": "3f1a9c20-4b5d-4e6f-8a90-1c2d3e4f5a6b",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "type": "business",
  "email": "ops@example.com",
  "phone": "+14155559999",
  "status": "CREATED",
  "verification_status": "unverified",
  "verification_mode": "automatic"
}

user.status_changed

{
  "event_id": "8c2b1d40-5e6f-4a7b-9c8d-2e3f4a5b6c7d",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "previous_status": "VERIFYING",
  "new_status": "REJECTED"
}

Fires on every transition. It is the one to subscribe to.

user.verification.accepted

{
  "event_id": "1d4e5f60-7a8b-4c9d-8e0f-3a4b5c6d7e8f",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "verification_status": "verified",
  "reasons": []
}

user.verification.failed

{
  "event_id": "9a8b7c60-1d2e-4f30-8a4b-5c6d7e8f9a0b",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "verification_status": "rejected",
  "reasons": ["Verification session expired"]
}

reasons exists only here. No read of the sub-client returns it.

user.liveness_completed

{
  "event_id": "5b6c7d80-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "person_reference_id": "0123456789abcdef0123456789abcdef",
  "result": "approved"
}

person_reference_id is null when the check was for the sub-client rather than one of its people.

Virtual account and deposits

virtual_account.activated

{
  "event_id": "2e3f4a50-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "status": "active"
}

The funds-ready signal. Nothing before it can receive money.

virtual_account.deposit_funds_received

{
  "event_id": "7c8d9e00-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "deposit_id": "4a5b6c70-8d9e-4f0a-8b1c-2d3e4f5a6b7c",
  "amount": "100.00",
  "currency": "USD",
  "created_at": "2026-09-01T12:00:00.000Z",
  "source": {
    "payment_rail": "wire",
    "description": "Invoice 4471",
    "sender_name": "Northwind Trading LLC",
    "trace_number": "20260901MMQFMP3K000123",
    "sender_bank_routing_number": "000000001"
  }
}

The rail-independent signal that money arrived.

virtual_account.deposit_funds_refunded

{
  "event_id": "6d7e8f90-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "deposit_id": "4a5b6c70-8d9e-4f0a-8b1c-2d3e4f5a6b7c",
  "amount": "100.00",
  "currency": "USD",
  "created_at": "2026-09-01T12:00:00.000Z",
  "return_details": {
    "code": "R01",
    "reason": "Insufficient funds at the sending bank",
    "refunded_at": "2026-09-02T09:00:00.000Z"
  }
}

Payouts

payout.status_changed

{
  "event_id": "0f1a2b30-4c5d-4e6f-8a7b-8c9d0e1f2a3b",
  "payout_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "amount": "1000.00",
  "currency": "USD",
  "recipient_amount": "986.50",
  "recipient_currency": "USD",
  "previous_status": "PROCESSING",
  "status": "IN_REVIEW",
  "updated_at": "2026-09-01T12:00:10.000Z"
}

Subscribe to this one. IN_REVIEW and KYT_PENDING arrive here and nowhere else.

payout.completed

{
  "event_id": "3b4c5d60-7e8f-4a9b-8c0d-1e2f3a4b5c6d",
  "payout_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "amount": "1000.00",
  "currency": "USD",
  "recipient_amount": "986.50",
  "recipient_currency": "USD",
  "status": "COMPLETED",
  "updated_at": "2026-09-01T12:04:00.000Z"
}

Amounts are strings. amount and recipient_amount differ by the fees and any conversion.

Requests for information

These reach a URL with no event filter, or one whose filter names them.

rfi.raised

{
  "event_id": "8e9f0a10-2b3c-4d5e-8f6a-7b8c9d0e1f2a",
  "rfi_id": "7f1c9a20-3b4d-4e5f-8a91-2c3d4e5f6a7b",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "to_status": "pending"
}

rfi.item_returned

{
  "event_id": "1a2b3c40-5d6e-4f70-8a8b-9c0d1e2f3a4b",
  "rfi_id": "7f1c9a20-3b4d-4e5f-8a91-2c3d4e5f6a7b",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "item_id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6a7b",
  "to_status": "pending",
  "review_note": "The document was issued more than 90 days ago."
}

to_status here is the item’s, not the request’s.

rfi.not_resolved

{
  "event_id": "4c5d6e70-8f9a-4b0c-8d1e-2f3a4b5c6d7e",
  "rfi_id": "7f1c9a20-3b4d-4e5f-8a91-2c3d4e5f6a7b",
  "user_id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "to_status": "not_resolved",
  "resolution_reason": "expired"
}

resolution_reason rides along only on this one — it is the difference between a deadline that ran out and an answer that was refused.

Every payload carries to_status read off the row that moved, rather than inferred from the event name. A handler that stores the event can reconstruct state without knowing which events existed on the day it was written.

Overview

Get started

Lifecycles

Webhooks

Sandbox

Compliance

Dashboard

Using the API

Building with AI

Notification examples

Sub-client

Virtual account and deposits

Payouts

Requests for information

​Sub-client

​Virtual account and deposits

​Payouts

​Requests for information

Sub-client

Virtual account and deposits

Payouts

Requests for information