Travel Rule Events

Webhook events

Webhook events represent specific actions or status changes within Ospree that trigger real-time notifications to your subscribed endpoint. Each event contains structured data, enabling your system to process and respond automatically. This section provides an overview of the available webhook events and their triggers.

Event Type	Event Name	Trigger
TRAVEL_RULE	INCOMING_TRANSFER	Triggered when a new incoming transfer request is received from a counterparty, requiring review and action.
TRAVEL_RULE	TRANSFER_ACCEPTED	Triggered when an outgoing transfer request has been "accepted" by the recipient and is ready for processing.
TRAVEL_RULE	TRANSFER_REJECTED	Triggered when an outgoing transfer request is "rejected" by the counterparty, preventing it from proceeding.
TRAVEL_RULE	TRANSFER_REPAIR	Triggered when an outgoing transfer needs to be repaired and resubmitted with corrections.
TRAVEL_RULE	TRANSFER_COMPLETED	Triggered when an incoming transfer has been successfully "completed".
TRAVEL_RULE	TRANSFER_CANCELED	Triggered when an incoming transfer has been "canceled" by the originator.

Webhook request schema

Below is the sample payload for travel rule events published to the webhook, along with the description of each field.

Field	Type	Description
request_id	UUIDV7	A unique identifier for the webhook request.
event_type	string	Specifies the module where the event originates (e.g., “TRAVEL_RULE”).
event_name	string	The specific event that triggered the webhook. See the list of Travel Rule events here.
timestamp	datetime	The date and time when the webhook request was sent.
error	object	Contains error details from the counterparty if a transfer request status is "REJECTED" or "REPAIR".
data	object	Contains travel rule request data.

Travel Rule data schema

Name	Type	Description
transfer_id	UUIDV7	Unieuq identifier for the transfer.
reference_id	string	Identifier for the transfer, defined by the sender. Example: transfer20250312040414
amount	number	The amount of the digital token being transferred.
amount_usd	number	The value of the digital token being transferred in USD.
dti	string	The unique DTI reference of the digital token. Refer to Token Identifier for the complete list of supported DTIs. Example: 4H95J0R2X
chain	string	The chain name of the digital token. Refer to Token Identifier for the complete list of supported chains. Example: bitcoin
symbol	string	The symbol of the digital token. Refer to Token Identifier for the complete list of supported token symbols. Example: BTC
protocol	string	Travel Rule protocol used for the information exchange. Examples: "flow" "trp" "trisa" "gtr"
transaction_hash	string	Blockchain transaction hash.
transfer_status	string	Refer to Transfer Status for the complete list of travel rule statuses.

Webhook request examples

Below are example requests for the different travel rule events.

INCOMING_TRANSFER

// Received when there is an incoming transfer from a counterparty VASP.
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "INCOMING_TRANSFER",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": null,
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": null,
    "transfer_status": "REVIEW"
  }
}

TRANSFER_ACCEPTED

// Received when the counterparty accepts the transfer request.
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "TRANSFER_ACCEPTED",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": null,
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": null,
    "transfer_status": "ACCEPTED"
  }
}

TRANSFER_REJECTED

// Received when the counterparty rejects the transfer request without retry.
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "TRANSFER_REJECTED",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": {
     "code": "REJECTED",
     "message": "No reason provided",
     "retry": false
  },
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": null,
    "transfer_status": "REJECTED"
  }
}

TRANSFER_REPAIR

// Received when the counterparty rejects the transfer request with retry.
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "TRANSFER_REPAIR",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": {
     "code": "UNKNOWN_WALLET_ADDRESS",
     "message": "Wallet address not available. Provide correct wallet address.",
     "retry": false
  },
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": null,
    "transfer_status": "REPAIR"
  }
}

TRANSFER_COMPLETED

// Received when the counterparty marks the transaction as "complete"
// and provides the transaction hash
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "TRANSFER_COMPLETED",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": null,
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": "b713dc87e18a771383a287344a82499d572cead39bdb025691404be441378c27",
    "transfer_status": "COMPLETED"
  }
}

TRANSFER_CANCELED

// Received when the counterparty cancels the transfer request before
// the request is accepted or rejected.
{
  "request_id": "01954725-66bb-7de1-a0f3-b5dbcdbd47b8",
  "event_type": "TRAVEL_RULE",
  "event_name": "TRANSFER_CANCELED",
  "timestamp": "2024-12-31T12:40:01.138096+00:00",
  "error": null,
  "data": {
    "transfer_id": "018f85d7-0650-7205-a1d5-011e9587c07c",
    "reference_id": "reference-transfer-01",
    "amount": 1.00,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "transaction_hash": null,
    "transfer_status": "CANCELED"
  }
}