KYC Redirect Flow with Webhook

How a parent account starts a hosted KYC for one of its sub-accounts via redirect (no email - you get a widget URL back and redirect the customer yourself), and registers a webhook to receive status updates. This is the same endpoint and the same webhook behaviour as the email flow - the only differences are flow_type: "redirect", customer_email is not required, and the response returns a widget_url instead of emailing a link.

Flow

Create the session

Parent calls Create KYC Session with flow_type: "redirect" and a webhook_url.

Vobiz returns a widget_url

Vobiz returns a widget_url. You redirect the customer to it.

Customer completes KYC

Customer completes KYC in the Vobiz-hosted widget.

Receive webhook events

Vobiz POSTs webhook events to your webhook_url at each stage (initiated → submitted → completed/failed).

1. Create the KYC session (register the webhook)

POST https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc-sessions

Auth: parent main account - X-Auth-ID: MA_xxxx + X-Auth-Token: <token> (or Authorization: Bearer <JWT>). The sub_auth_id path param (SA_xxxx) identifies the sub-account being verified.

Body:

{
  "flow_type": "redirect",
  "webhook_url": "https://your-app.example.com/kyc/webhook",
  "redirect_url": "https://your-app.example.com/kyc/done",
  "expires_in_days": 30,
  "metadata": { "your_ref": "anything you want echoed back" }
}

Field	Required	Notes
`flow_type`	yes	`"redirect"` for this flow.
`webhook_url`	no but needed for callbacks	HTTPS endpoint that receives the events below. No `webhook_url` = no callbacks.
`redirect_url`	yes (redirect flow)	Where the widget sends the customer after they finish KYC. Required for `flow_type: "redirect"`.
`customer_email`	no	Not required for redirect flow (no email is sent).
`expires_in_days`	no	Days before the link expires. Defaults to `7` (the example above overrides it to `30`).
`metadata`	no	Arbitrary JSON, echoed back in every webhook payload. Mirrors the partner KYC Sessions endpoint.

account_auth_id in the schema is set automatically from the path sub_auth_id for this flow - you don’t need to send it.

Response 201:

{
  "session_id": "b6a1f3c2-7a44-4e2b-9c11-...",
  "account_auth_id": "SA_xxxx",
  "customer_email": null,
  "status": "link_ready",
  "expires_at": "2026-07-04T08:51:10Z",
  "widget_url": "https://kyc.vobiz.ai/verify?token=kst_cb1b3fda...",
  "message": "Redirect your customer to widget_url to begin."
}

Redirect the customer to widget_url to start KYC. (kyc_link is only returned in dev for testing.)

2. Webhook events you’ll receive

Identical to the email flow - Vobiz POSTs JSON to your webhook_url as the session progresses:

Event	When
`kyc.initiated`	Session created.
`kyc.submitted`	Customer submitted their documents.
`kyc.completed`	Verification passed.
`kyc.failed`	Verification failed.
`kyc.session_expired`	Link expired before completion.
`kyc.session_revoked`	Session manually revoked.

Payload:

{
  "event": "kyc.completed",
  "timestamp": "2026-06-04T08:51:10Z",
  "session_id": "b6a1f3c2-7a44-4e2b-9c11-...",
  "account_auth_id": "SA_xxxx",
  "customer_email": null,
  "kyc_type": "individual",
  "session_status": "kyc_completed",
  "metadata": { "your_ref": "anything you want echoed back" },
  "created_at": "2026-06-04T08:40:00+00:00",
  "updated_at": "2026-06-04T08:51:10+00:00"
}

3. Verify the signature

Every delivery includes an HMAC signature header (same as email flow):

X-Vobiz-Signature: sha256=<hex>

Algorithm: HMAC-SHA256 over the raw request body.
Secret: your parent account’s auth_token.

Verify (Python):

import hmac, hashlib

def verify(raw_body: bytes, header: str, auth_token: str) -> bool:
    expected = "sha256=" + hmac.new(auth_token.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Return 2xx to acknowledge. Failed deliveries are retried with exponential backoff.

cURL example

Copy-paste starter - create a redirect-flow session with both your webhook and redirect URLs in one call:

curl -X POST "https://api.vobiz.ai/api/v1/sub-accounts/SA_XXXX/kyc-sessions" \
  -H "X-Auth-ID: MA_XXXX" \
  -H "X-Auth-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_type": "redirect",
    "webhook_url": "https://your-app.example.com/kyc/webhook",
    "redirect_url": "https://your-app.example.com/kyc/done"
  }'

Email vs Redirect

Same endpoint, same webhooks.

email → Vobiz emails the customer the link (needs customer_email). See the email flow.
redirect → you get widget_url back and redirect the customer yourself (no email).

​Flow

​1. Create the KYC session (register the webhook)

​2. Webhook events you’ll receive

​3. Verify the signature

​cURL example

​Email vs Redirect

Flow

1. Create the KYC session (register the webhook)

2. Webhook events you’ll receive

3. Verify the signature

cURL example

Email vs Redirect