Skip to main content
Event Name: transfer_state_updated
This event is emitted every time a transfer advances to a new state in its lifecycle, from when the request is received until it is completed or fails.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "transfer_state_updated",
  "timestamp": "2025-06-19T17:14:13.123Z",
  "data": {
    "transferId": "550e8400-e29b-41d4-a716-446655440001",
    "state": "COMPLETED",
    "error": "Insufficient funds"
  }
}

​
Field Description

​
id
string
required
Unique event ID (UUID)
​
event
string
required
Event type - always transfer_state_updated for this webhook
​
timestamp
string
required
Timestamp of the event (ISO 8601 format)
​
data
object
required
Event data
​
data.transferId
string
required
Unique transfer ID (UUID)
​
data.state
string
required
Transfer state (see possible values in Transfer States section)
​
data.error
string
Error message if the transfer failed

​
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 === 'transfer_state_updated') {
    const { transferId, state, error } = data;
    
    // Process transfer state update
    console.log(`Transfer ${transferId} state changed to: ${state}`);
    
    if (error) {
      console.log(`Transfer error: ${error}`);
    }
    
    // Update your internal systems
    await updateTransferStatus(transferId, state);
    
    // Handle specific states
    switch (state) {
      case 'COMPLETED':
        await handleTransferCompleted(transferId);
        break;
      case 'ERROR':
        await handleTransferError(transferId, error);
        break;
      case 'CONFIRMED':
        await handleTransferConfirmed(transferId);
        break;
    }
    
    // Respond with success
    res.status(200).json({ received: true });
  }
});