Skip to main content
Event Name: kyc_state_updated
This event is emitted when the overall verification status of the user is upgraded or downgraded, typically after completing or failing verification sessions.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "kyc_state_updated",
  "timestamp": "2025-06-19T17:14:13.123Z",
  "data": {
    "kyc_id": 12345,
    "user_id": "550e8400-e29b-41d4-a716-446655440001",
    "state": "REGULAR"
  }
}

​
Field Description

​
id
string
required
Unique event identifier (UUID)
​
event
string
required
Event type - always kyc_state_updated for this webhook
​
timestamp
string
required
Event timestamp in ISO 8601 format
​
data
object
required
Contains the event data
​
data.kyc_id
integer
required
Unique KYC record ID
​
data.user_id
string
required
Unique user ID (UUID)
​
data.state
string
required
Current KYC level: “REGULAR” (full KYC) or “LIGHT” (basic KYC)

​
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_state_updated') {
    const { kyc_id, user_id, state } = data;
    
    // Process KYC state update
    console.log(`User ${user_id} KYC state updated to ${state}`);
    
    // Update your internal systems
    await updateUserKycLevel(user_id, state);
    
    // Respond with success
    res.status(200).json({ received: true });
  }
});