kyc_session.failed - Contro

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"
}

Field	Type	Description
`kycSessionId`	string	KYC session ID
`externalUserId`	string	Your external user ID linked to this session
`status`	string	Always `"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 code	Meaning
`200`	Event received and processed
`202`	Event received, will process asynchronously
Any non-2xx	Delivery 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");
});