Skip to main content
Endl sends onboarding webhooks when you create or import a customer and as that customer moves through identity verification (KYC for individuals, KYB for businesses). Use them to keep your own records up to date without polling Get customer. All six events:
  • relate to a customer, so data.id and data.customerId both hold the customer’s cus_… id
  • use the standard envelope, signature and retry rules from the Webhooks guide
  • apply to both INDIVIDUAL and BUSINESS customers; data.userType tells you which
Subscribing: use "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

Things to know:
  • One event per status change. An event fires only when the status actually changes. A repeat of the same status sends nothing.
  • kyc.submitted can arrive more than once, for example once for PENDING and again for IN_REVIEW, and again after each resubmission.
  • kyc.action_required can repeat if the customer resubmits and still needs another correction.
  • Imported customers get a customer.created event that already carries their imported status (COMPLETED, REJECTED or PENDING). No separate kyc.* event follows for that starting status.
  • Order isn’t guaranteed across retries. Use eventCreatedAt and status to 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 new cus_ 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 to PENDING (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 is RESUBMISSION_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:
  1. Tell the customer what to fix, using reason.
  2. Have them resubmit, either through the KYC link or by uploading documents again.
  3. Expect kyc.submitted next.

kyc.on_hold

When: verification is paused for manual or compliance review. The status is ON_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 is COMPLETED, 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 is REJECTED, 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_INVALID or SELFIE_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. Use rejectionCodes for 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 eventCreatedAt is older than the latest one you’ve processed for that customer.
  • Treat COMPLETED and REJECTED as final. Only RESUBMISSION_REQUIRED and ON_HOLD can 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.