Skip to main content
Event Name: kyb_state_updated
This event is emitted when the overall KYB verification level changes for a business user, typically after a verification process is completed, downgraded, or expires.

​
Event Payload

The webhook payload contains the following structure:
Example Payload
{
  "eventId": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "eventType": "kyb_state_updated",
  "timestamp": "2026-03-21T23:55:00.000Z",
  "data": {
    "kybId": 42,
    "userId": "c8e2f1a0-4b3d-4e5f-8a9b-0c1d2e3f4a5b",
    "state": "REGULAR"
  }
}

​
Field Description

​
eventId
string
required
Unique event identifier (UUID)
​
eventType
string
required
Event type - always kyb_state_updated for this webhook
​
timestamp
string
required
Event timestamp in ISO 8601 format
​
data
object
required
Contains the event data
​
data.kybId
integer
required
Unique KYB record ID
​
data.userId
string
required
Unique business user ID (UUID)
​
data.state
string
required
Current KYB level. Common values include REGULAR and LIGHT

​
When This Event Is Sent

This webhook is sent when the KYB record changes its overall verification level for a business user. Typical scenarios include:
  • A verification flow upgrades the business user to REGULAR
  • A review or business rule downgrades the business user to LIGHT

​
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 { eventType, data } = req.body;

  if (eventType === 'kyb_state_updated') {
    const { kybId, userId, state } = data;

    console.log(
      `KYB ${kybId} for business user ${userId} changed to ${state}`
    );

    await updateBusinessUserKybLevel(userId, state);

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