KYC link status specific events
| Event | Description | Default |
|---|---|---|
kyc_link.pending | Triggered when a KYC link is generated | On |
kyc_link.requires_action | Triggered when the individual must resubmit through the same link | On |
kyc_link.approved | Triggered when the verification is approved | On |
kyc_link.rejected | Triggered when the verification is rejected | On |
kyc_link.expired | Triggered when a KYC link expires or is expired through the API | On |
Payload
Thedata.kyc_link object in every event has the same shape as the Fetch KYC Link response. Fields without a value are sent as null rather than omitted: completed_at is null until the link is approved, rejected or expired, and verification_result is null until the link is approved or rejected. See KYC Link for the field reference. Unlike the API response, document_number is masked in webhook payloads.
Sample Events
kyc_link.pending
{
"type": "kyc_link.pending",
"id": "evt_aaaaaaaaaaaaaaaaaaa1",
"object": "event",
"created_at": "2026-09-25T10:15:01Z",
"data": {
"entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
"kyc_link": {
"url": "https://verify.example.com/kyc/demo-link-001",
"status": "pending",
"created_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-25T10:00:00Z",
"completed_at": null,
"verification_result": null,
"metadata": null
}
}
}
kyc_link.requires_action
{
"type": "kyc_link.requires_action",
"id": "evt_aaaaaaaaaaaaaaaaaaa2",
"object": "event",
"created_at": "2026-09-25T10:15:01Z",
"data": {
"entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
"kyc_link": {
"url": "https://verify.example.com/kyc/demo-link-001",
"status": "requires_action",
"created_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-25T10:00:00Z",
"completed_at": null,
"verification_result": null,
"metadata": {
"customer_reference": "customer_demo_001"
}
}
}
}
kyc_link.approved
{
"type": "kyc_link.approved",
"id": "evt_aaaaaaaaaaaaaaaaaaa3",
"object": "event",
"created_at": "2026-09-25T10:15:01Z",
"data": {
"entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
"kyc_link": {
"url": "https://verify.example.com/kyc/demo-link-001",
"status": "approved",
"created_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-25T10:00:00Z",
"completed_at": "2026-09-25T10:15:00Z",
"verification_result": {
"outcome": "approved",
"rejection_type": null,
"rejection_reasons": [],
"checks": {
"identity": {
"status": "passed",
"document_type": "ID_CARD",
"document_country": "IND",
"document_number": "123****789",
"document_expiry": "2035-12-31"
},
"address": {
"status": "passed",
"document_type": "UTILITY_BILL"
},
"selfie": {
"status": "passed",
"document_type": "SELFIE",
"document_country": "IND",
"document_number": null,
"document_expiry": null
}
},
"extracted_data": {
"first_name": "Alex",
"last_name": "Morgan",
"date_of_birth": "1990-05-15",
"nationality": "IND",
"address": {
"line1": "12 Example Street",
"line2": "Apartment 4B",
"city": "Example City",
"state": "Example State",
"postal_code": "110001",
"country": "IND"
}
}
},
"metadata": {
"customer_reference": "customer_demo_001"
}
}
}
}
kyc_link.rejected
{
"type": "kyc_link.rejected",
"id": "evt_aaaaaaaaaaaaaaaaaaa4",
"object": "event",
"created_at": "2026-09-25T10:15:01Z",
"data": {
"entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
"kyc_link": {
"url": "https://verify.example.com/kyc/demo-link-001",
"status": "rejected",
"created_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-25T10:00:00Z",
"completed_at": "2026-09-25T10:15:00Z",
"verification_result": {
"outcome": "rejected",
"rejection_type": "FINAL",
"rejection_reasons": [
{
"code": "SELFIE_MISMATCH",
"description": "The submitted selfie could not be matched to the identity document.",
"user_message": "Please contact support for assistance."
}
],
"checks": {
"identity": {
"status": "failed",
"document_type": "PASSPORT",
"document_country": "IND",
"document_number": "Z12****678",
"document_expiry": "2032-08-14"
},
"address": {
"status": "failed",
"document_type": "UTILITY_BILL"
},
"selfie": {
"status": "failed",
"document_type": "SELFIE",
"document_country": "IND",
"document_number": null,
"document_expiry": null
}
},
"extracted_data": {
"first_name": "Alex",
"last_name": "Morgan",
"date_of_birth": "1990-05-15",
"nationality": "IND",
"address": {
"line1": "12 Example Street",
"line2": "Apartment 4B",
"city": "Example City",
"state": "Example State",
"postal_code": "110001",
"country": "IND"
}
}
},
"metadata": {
"customer_reference": "customer_demo_001"
}
}
}
}
kyc_link.expired
{
"type": "kyc_link.expired",
"id": "evt_aaaaaaaaaaaaaaaaaaa5",
"object": "event",
"created_at": "2026-09-26T10:12:01Z",
"data": {
"entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
"kyc_link": {
"url": "https://verify.example.com/kyc/demo-link-001",
"status": "expired",
"created_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-09-26T10:00:00Z",
"completed_at": "2026-09-26T10:12:00Z",
"verification_result": null,
"metadata": {
"customer_reference": "customer_demo_001"
}
}
}
}