> ## Documentation Index
> Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# kyc_session.failed

> Fired when a KYC session fails verification

## Event: `kyc_session.failed`

Sent when a KYC session (initiated via [web link](/partner/kyc-via-web-link) or [Sumsub](/partner/kyc-via-sumsub)) is rejected by the verification provider.

## Payload

```json theme={null}
{
  "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](/partner/webhooks#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

```javascript theme={null}
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");
});
```