All six events:
- relate to a customer, so
data.idanddata.customerIdboth hold the customer’scus_…id - use the standard envelope, signature and retry rules from the Webhooks guide
- apply to both
INDIVIDUALandBUSINESScustomers;data.userTypetells you which
"eventFilter": ["customer.*", "kyc.*"] to receive all of them,
or list individual event types.
Payload fields
Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change. Read
optional fields defensively.
Status values
Typical lifecycle
- One event per status change. An event fires only when the status actually changes. A repeat of the same status sends nothing.
kyc.submittedcan arrive more than once, for example once forPENDINGand again forIN_REVIEW, and again after each resubmission.kyc.action_requiredcan repeat if the customer resubmits and still needs another correction.- Imported customers get a
customer.createdevent that already carries their imported status (COMPLETED,REJECTEDorPENDING). No separatekyc.*event follows for that starting status. - Order isn’t guaranteed across retries. Use
eventCreatedAtandstatusto make sure you never overwrite a newer state with an older one. If you’re unsure, call Get customer: the API is always the source of truth.
Events in detail
customer.created
When: a customer is created (Create customer) or imported, for both individuals and businesses. This is the first event you get for a newcus_ id.
Payload: status is INITIATED for a newly created customer, or, for an
imported customer, the imported verification outcome: COMPLETED, REJECTED or
PENDING. Plus userType.
What to do: store the cus_ id and start tracking the customer. If status is
INITIATED, send the customer the KYC link.
kyc.submitted
When: the customer’s verification moves toPENDING (submitted and being
processed) or IN_REVIEW (under review).
Payload: status (PENDING or IN_REVIEW), previousStatus when available
(for example RESUBMISSION_REQUIRED after a resubmission), and userType.
What to do: show the customer as “verification in progress”. You don’t need to
do anything else; wait for a final outcome.
kyc.action_required
When: verification can’t be completed until the customer fixes something, such as a blurry photo, a missing page or an expired document. The status isRESUBMISSION_REQUIRED. This status isn’t final.
Payload: status (RESUBMISSION_REQUIRED), reason (what needs fixing,
written so you can show it to the customer), rejectionCodes (machine-readable
codes), previousStatus and userType.
What to do:
- Tell the customer what to fix, using
reason. - Have them resubmit, either through the KYC link or by uploading documents again.
- Expect
kyc.submittednext.
kyc.on_hold
When: verification is paused for manual or compliance review. The status isON_HOLD. This status isn’t final.
Payload: status (ON_HOLD), previousStatus and userType. No reason is sent.
What to do: show the customer as “under review”. The customer doesn’t need to do
anything. Wait for the next event: usually kyc.completed or kyc.rejected, and
sometimes kyc.action_required.
kyc.completed
When: the customer passes verification. The status isCOMPLETED, and it’s final.
Payload: status (COMPLETED), previousStatus and userType. No reason is sent.
What to do: mark the customer as verified. They can now use the products that
require KYC or KYB, such as accounts, payouts and cards.
kyc.rejected
When: the customer fails verification. The status isREJECTED, and it’s final:
the customer can’t retry.
Payload: status (REJECTED), reason and rejectionCodes when available,
previousStatus and userType.
What to do: mark the customer as rejected and don’t offer services that need KYC.
Some rejection reasons, such as compliance or screening matches, are deliberately
not shared. In that case reason or rejectionCodes may be missing or only partly
filled in.
rejectionCodes
- These codes come from the verification provider and describe what went wrong, for
example
UNSATISFACTORY_PHOTOS,DOCUMENT_PAGE_MISSING,ID_INVALIDorSELFIE_MISMATCH. - Treat the list as open-ended. New codes can appear, so don’t reject a delivery because you don’t recognise a code.
- Compliance-sensitive codes are never sent, even when they caused the outcome. That includes sanctions, criminal-record, blacklist and fraud-pattern matches. A rejection can therefore arrive with an empty or partial list.
- For anything you show the customer, use
reason. UserejectionCodesfor routing and analytics.
Best practices
- Verify the signature, then deduplicate on
eventId, then act. Delivery is at least once, so the same event can arrive twice. - Don’t move a customer backwards. Ignore an event whose
eventCreatedAtis older than the latest one you’ve processed for that customer. - Treat
COMPLETEDandREJECTEDas final. OnlyRESUBMISSION_REQUIREDandON_HOLDcan change to another status. - Use the API as the source of truth. Webhooks tell you that something changed. If an event is missing or out of order, call Get customer.
- Subscribe with globs (
kyc.*,customer.*) so you automatically receive new onboarding events Endl adds later.