Skip to main content
Event Name: kyc_session_failed
This event is emitted when a KYC verification session fails and the entity could not be verified. The session state is REJECTED.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "c4f6d7a7-cf31-4ae4-af15-7571c0e7f743",
  "event": "kyc_session_failed",
  "timestamp": "2026-03-17T16:49:37.314Z",
  "data": {
    "sessionId": "43b972aa-88c2-4791-9a7b-7a338e182a3c",
    "userId": "15f8e008-d774-4a0f-bc39-a78c8e4859c9",
    "entityType": "user",
    "checks": [
      {
        "type": "manual_review",
        "state": 2,
        "data": {
          "type": "manual_review",
          "provider": "MOCK",
          "timestamp": "2026-03-17T12:40:24-04:00"
        },
        "reasons": [
          {
            "type": "ManualReview",
            "code": "KYC.DOC.DETERIORATED",
            "message": "Document deteriorated or illegible (stains, tears).",
            "category": "DOC"
          }
        ]
      }
    ]
  }
}

​
Field Description

​
id
string
required
Unique event identifier (UUID)
​
event
string
required
Event type - always kyc_session_failed for this webhook
​
timestamp
string
required
Event timestamp in ISO 8601 format
​
data
object
required
Contains the event data
​
data.sessionId
string
required
Unique KYC session ID (UUID)
​
data.userId
string
Unique user ID (UUID)
​
data.entityType
string
required
Entity type associated with the KYC session. Possible values: user, related-party
​
data.relatedPartyId
string
Unique related party ID (UUID)
​
data.checks
array
List of failed verification checks included in the kyc_session_failed event
​
data.checks[].type
string
required
Type of verification check, for example manual_review
​
data.checks[].state
integer
required
Check state. Current values are 1 for validated and 2 for refused
​
data.checks[].data
object
required
Additional raw check data. Its structure varies depending on the check type and may include provider-specific fields
​
data.checks[].reasons
array
Reasons associated with a refused check. This field is typically omitted or empty for validated checks
​
data.checks[].reasons[].type
string
required
Reason type or issue category detected during verification
​
data.checks[].reasons[].code
string
required
Machine-readable code identifying the failure reason
​
data.checks[].reasons[].message
string
required
Human-readable explanation of the failure reason
​
data.checks[].reasons[].category
string
Optional higher-level classification for the reason

​
Expected Responses

Success Response

HTTP 200 OKThe webhook was processed successfully.

Client Error

HTTP 4xx StatusClient-side error. Will not be retried.

Server Error

HTTP 5xx StatusServer-side error. Will be retried with exponential backoff.

​
Implementation Example

app.post('/webhooks/ralio', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'kyc_session_failed') {
    const { sessionId, entityType, userId, relatedPartyId, checks = [] } = data;
    const subjectId = userId ?? relatedPartyId;

    console.log(`KYC session ${sessionId} failed for ${entityType} ${subjectId}`);
    for (const check of checks) {
      for (const reason of check.reasons ?? []) {
        console.log(`Check ${check.type} failed with code ${reason.code}: ${reason.message}`);
      }
    }

    await updateKycSessionStatus(sessionId, 'REJECTED');

    if (entityType === 'user' && userId) {
      await notifyUserVerificationFailed(userId);
    }

    if (entityType === 'related-party' && relatedPartyId) {
      await notifyRelatedPartyVerificationFailed(relatedPartyId);
    }

    res.status(200).json({ received: true });
  }
});