Webhook 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.

The address ownership verification webhook notification is currently undergoing testing.

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.
ADDRESS_VERIFICATION	ADDRESS_VERIFICATION_COMPLETED	Triggered when address ownership has been successfully verified.
ADDRESS_VERIFICATION	ADDRESS_VERIFICATION_FAILED	Triggered when address ownership has failed verification.

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.

Address Verification data schema

Name	Type	Description
address	string	Unique blockchain identifier. Example: 1JjYpRXfPntVEJqAjxsYmvFjjJBdJyaJ2k
chain	string	Blockchain network name. Example: bitcoin
is_validated	boolean	Indicates whether the address exists and has a transaction history.
is_self_hosted	boolean	Shows if the address has been labeled as self-hosted.
is_verified	boolean	Confirms if ownership has been cryptographically proven via a digital signature.
is_customer	boolean	Flags whether the address is associated with a known customer account.
reference_id	string	Internal reference ID of the associated account.

Webhook request examples

Travel Rule

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_type": "INSTRUCTION",
    "originator_address_is_self_hosted": true,
    "beneficiary_address_is_self_hosted": false
  }
}

TRANSFER_ACCEPTED

TRANSFER_REJECTED

TRANSFER_REPAIR

TRANSFER_COMPLETED

TRANSFER_CANCELED

Address Verification

Below are example requests for the different address verification events.

ADDRESS_VERIFICATION_COMPLETED

{
  "request_id": "069158dd-5dac-7d60-8000-a4e11e7567e0",
  "event_type": "ADDRESS_VERIFICATION",
  "event_name": "ADDRESS_VERIFICATION_COMPLETED",
  "timestamp": "2025-11-13T07:50:45.854720",
  "error": null,
  "data": {
    "address": "0xe0e643722e83bc56c73937cfae22ce369a80fa4a",
    "chain": "ETH",
    "is_validated": false,
    "is_self_hosted": true,
    "is_verified": true,
    "is_customer": null,
    "reference_id": null
  }
}

ADDRESS_VERIFICATION_FAILED