Skip to main content
Event Name: kyc_expiration_warning
This event is emitted when an active KYC verification is approaching its document expiration date. It is intended to give merchants enough time to trigger a new KYC verification session before the current verification expires.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "kyc_expiration_warning",
  "timestamp": "2025-06-19T17:14:13.123Z",
  "data": {
    "kycId": 12345,
    "entityType": "user",
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "expirationDate": "2025-07-03",
    "daysRemaining": 14,
    "action": "Create a new KYC verification session for the affected user before their current verification expires."
  }
}

​
Field Description

​
id
string
required
Unique event identifier (UUID)
​
event
string
required
Event type - always kyc_expiration_warning for this webhook
​
timestamp
string
required
Event timestamp in ISO 8601 format
​
data
object
required
Contains the event data
​
data.kycId
integer
required
Unique KYC record identifier
​
data.entityType
string
required
Entity type associated with the KYC record. Possible values: user, related-party
​
data.userId
string
Unique user ID (UUID)
​
data.relatedPartyId
string
Unique related party ID (UUID)
​
data.expirationDate
string
required
Document expiration date in YYYY-MM-DD format
​
data.daysRemaining
integer
required
Number of days remaining before the KYC document expires
​
data.action
string
required
Recommended action for the merchant to prevent the KYC from expiring

​
When This Event Is Sent

This webhook is sent when a KYC record is close to expiration and has not been previously notified. Typical conditions include:
  • The KYC is still in a valid operational state
  • The document expiration date is within the warning threshold
  • A warning has not already been sent for that KYC
In the current implementation, the warning threshold is 14 days before expiration.

​
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_expiration_warning') {
    const { kycId, entityType, userId, relatedPartyId, expirationDate, daysRemaining, action } = data;
    const subjectId = userId ?? relatedPartyId;

    console.log(
      `KYC ${kycId} for ${entityType} ${subjectId} expires on ${expirationDate} (${daysRemaining} days remaining)`
    );

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

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

    console.log(`Recommended action: ${action}`);

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