All customer webhooks are sent to your collection_url.
Parameter overview
| Parameter | Description |
|---|
message | Human-readable description of the event. |
event_type | Event type identifier (e.g. customer.status_changed). |
customer_id | Unique ID of the customer. |
customer_email | The customer’s email address. |
old_status | The customer’s previous verification status. |
new_status | The customer’s new verification status. |
comment | Optional comment explaining the status change (e.g. rejection reason). |
updated_at | ISO 8601 timestamp of when the status changed. |
event_id | Unique identifier for this webhook event. |
type | Always customer for customer events. |
The event
Customer-level transitions all fire a single event on the wire: event_type = customer.status_changed. The old_status and new_status fields tell you which way the customer just moved — for example PENDING → VERIFIED, PROCESSING → REJECTED, or REJECTED → PROCESSING (after a re-submission).
You will commonly hear about these as “the verified webhook” or “the rejected webhook” — that’s shorthand for the same customer.status_changed event with new_status=VERIFIED or new_status=REJECTED. There are no separate event_type values for them on the wire.
When the event fires
- Verification approved —
new_status=VERIFIED. The customer can now be used for Virtual Bank Account creation, payouts, and any other operation that requires a verified customer.
- Verification rejected —
new_status=REJECTED. Check the comment field for the customer-level reason. For business customers, also fetch GET /api/external/customer/{id} to read per-owner and per-document admin_comments arrays — the actionable per-record feedback lives there.
- Submitted for review (business customers) —
new_status=PROCESSING, fired right after POST /api/external/customer/{id}/submit. Indicates the customer is now locked and under compliance review.
- Reverted by admin —
new_status=PENDING after a previously-VERIFIED or REJECTED customer is moved back to PENDING by our operations team. Rare.
Verification is not instant. After documents are uploaded (individual) or /submit is called (business), the customer enters a review process. You will not receive this webhook immediately — it arrives once the review is complete.For individual customers, the review finishes within a few minutes in most cases; up to 2 hours under additional screening. Do not raise support tickets within that window. Escalate only if pending for 5 hours or more.For business customers, KYB review typically takes 1–5 business days. Do not raise tickets within that window. Escalate only if PROCESSING for more than 5 business days. See Business customer KYB. Example payload
{
"message": "Customer verification status updated",
"event_type": "customer.status_changed",
"customer_id": "cust_abc123",
"customer_email": "john@example.com",
"old_status": "PENDING",
"new_status": "VERIFIED",
"comment": null,
"updated_at": "2026-03-13T14:30:00.000Z",
"event_id": "evt_def456",
"type": "customer"
}
Rejected example
{
"message": "Customer verification status updated",
"event_type": "customer.status_changed",
"customer_id": "cust_abc123",
"customer_email": "john@example.com",
"old_status": "PENDING",
"new_status": "REJECTED",
"comment": "Identity document is expired.",
"updated_at": "2026-03-13T14:30:00.000Z",
"event_id": "evt_ghi789",
"type": "customer"
}
Possible statuses
| Status | Description |
|---|
PENDING | Customer is editable; verification has not started yet. For individuals, this is the state right after creation. For businesses, this is the state until you call POST /api/external/customer/{id}/submit. |
PROCESSING | Business customers only. Customer is locked and under compliance review. Typically lasts 1–5 business days. Owner and KYB-document state changes during this window are not separately webhooked — wait for the customer-level transition. |
VERIFIED | Customer KYC/KYB has been approved. The customer can now be used for payouts and (where supported) Virtual Bank Account creation. |
REJECTED | Customer was rejected. Check the comment field for the customer-level reason. For business customers, also fetch GET /api/external/customer/{id} to read per-owner and per-KYB-document admin_comments arrays — the per-record detail is where the actionable feedback lives. See Handling KYB rejections. |
No per-owner or per-KYB-document webhooks. For business customers, individual owner and document state changes during review do not emit webhooks. The customer-level customer.status_changed event is the only signal — when it fires with new_status=VERIFIED or new_status=REJECTED, fetch the customer to read the per-record state.
Verification timing
- Individual customers: typically a few minutes; up to 2 hours under additional screening. Do not escalate before 2 hours; contact operations only if pending for 5 hours or more.
- Business customers: typically 1–5 business days. Compliance reviews each owner and each KYB document individually. Do not escalate within the 5-business-day window. See Business customer KYB for the full lifecycle.
