Skip to main content
Event Name: kyc_session_manual_review
This event is emitted when a KYC verification session cannot be conclusively resolved by automatic checks and must be reviewed manually. The session state is REVIEW.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "5ebcc965-3d96-4af1-8e75-9c97c26ef6da",
  "event": "kyc_session_manual_review",
  "timestamp": "2026-03-17T16:41:28.447Z",
  "data": {
    "sessionId": "f4456ae8-bf7b-4d48-a2a6-4fd0f3d598e9",
    "userId": "d67f9318-bce0-4600-98fc-e0d98d2b1a31",
    "entityType": "user"
  }
}

​
Field Description

​
id
string
required
Unique event identifier (UUID)
​
event
string
required
Event type - always kyc_session_manual_review 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)

​
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_manual_review') {
    const { sessionId, entityType, userId, relatedPartyId } = data;
    const subjectId = userId ?? relatedPartyId;

    console.log(`KYC session ${sessionId} moved to manual review for ${entityType} ${subjectId}`);

    await updateKycSessionStatus(sessionId, 'REVIEW');

    if (entityType === 'user' && userId) {
      await notifyComplianceTeam(userId, sessionId);
    }

    if (entityType === 'related-party' && relatedPartyId) {
      await notifyRelatedPartyComplianceTeam(relatedPartyId, sessionId);
    }

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