Skip to main content
Event Name: kyc_session_failed
This can occur due to various reasons such as invalid documents, failed biometric verification, or detection of fraudulent activity. The session state is REJECTED.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "kyc_session_failed",
  "timestamp": "2025-06-19T17:14:13.123Z",
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440002",
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "checks": [
      {
        "type": "document-verification",
        "state": "Refused",
        "data": {},
        "reasons": [
          {
            "type": "document",
            "code": "EXPIRED_DOCUMENT",
            "message": "The provided document has expired"
          }
        ]
      },
      {
        "type": "face-matching",
        "state": "Refused",
        "data": {},
        "reasons": [
          {
            "type": "face-match",
            "code": "NO_MATCH",
            "message": "Face does not match the document photo"
          }
        ]
      }
    ]
  }
}

​
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
required
Unique user ID (UUID)
​
data.checks
array
required
List of verification checks showing failure reasons
​
data.checks[].type
string
required
Type of check (e.g., “document-verification”, “face-matching”)
​
data.checks[].state
string
required
Check state (typically “Refused” for failed sessions)
​
data.checks[].data
object
required
Additional check data (format varies by check type)
​
data.checks[].reasons
array
required
Reasons why the check failed
​
data.checks[].reasons[].type
string
Type of reason/issue detected
​
data.checks[].reasons[].code
string
Code identifying the specific failure reason
​
data.checks[].reasons[].message
string
Human-readable description of the failure

​
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', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'kyc_session_failed') {
    const { sessionId, userId, checks } = data;
    
    // Process failed session
    console.log(`KYC session ${sessionId} failed for user ${userId}`);
    
    // Extract failure reasons
    const failures = checks.flatMap(check => 
      check.reasons.map(reason => ({
        checkType: check.type,
        code: reason.code,
        message: reason.message
      }))
    );
    
    console.log(`Failure reasons:`, failures);
    
    // Update your internal systems
    await updateKycSessionStatus(sessionId, 'REJECTED');
    await notifyUserVerificationFailed(userId, failures);
    
    // Respond with success
    res.status(200).json({ received: true });
  }
});