Skip to main content

​
Event: kyc_session.failed

Sent when a KYC session (initiated via web link or Sumsub) is rejected by the verification provider.

​
Payload

{
  "kycSessionId": "kycs_abc123",
  "externalUserId": "your-user-id-123",
  "status": "failed"
}
FieldTypeDescription
kycSessionIdstringKYC session ID
externalUserIdstringYour external user ID linked to this session
statusstringAlways "failed" for this event

​
Response

Your endpoint must return a 2xx status code within 30 seconds to acknowledge receipt. Any non-2xx response or timeout triggers the retry policy.
Status codeMeaning
200Event received and processed
202Event received, will process asynchronously
Any non-2xxDelivery failed — will retry

​
Example handler

app.post("/webhooks/contro", (req, res) => {
  const eventType = req.headers["x-contro-event"];

  if (eventType === "kyc_session.failed") {
    const { kycSessionId, externalUserId } = req.body;
    // Notify the user that KYC failed and they may need to retry
  }

  res.status(200).send("OK");
});