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

{% hint style="success" %}
The address ownership verification webhook notification is currently undergoing testing.
{% endhint %}

<table><thead><tr><th width="220.8680419921875">Event Type</th><th width="246.02685546875">Event Name</th><th>Trigger</th></tr></thead><tbody><tr><td>TRAVEL_RULE</td><td>INCOMING_TRANSFER</td><td>Triggered when a new incoming transfer request is received from a counterparty, requiring review and action.</td></tr><tr><td>TRAVEL_RULE</td><td>TRANSFER_ACCEPTED</td><td>Triggered when an outgoing transfer request has been "accepted" by the recipient and is ready for processing.</td></tr><tr><td>TRAVEL_RULE</td><td>TRANSFER_REJECTED</td><td>Triggered when an outgoing transfer request is "rejected" by the counterparty, preventing it from proceeding.</td></tr><tr><td>TRAVEL_RULE</td><td>TRANSFER_REPAIR</td><td>Triggered when an outgoing transfer needs to be repaired and resubmitted with corrections.</td></tr><tr><td>TRAVEL_RULE</td><td>TRANSFER_COMPLETED</td><td>Triggered when an incoming transfer has been successfully "completed".</td></tr><tr><td>TRAVEL_RULE</td><td>TRANSFER_CANCELED</td><td>Triggered when an incoming transfer has been "canceled" by the originator.</td></tr><tr><td>ADDRESS_VERIFICATION</td><td>ADDRESS_VERIFICATION_COMPLETED</td><td>Triggered when address ownership has been successfully verified.</td></tr><tr><td>ADDRESS_VERIFICATION</td><td>ADDRESS_VERIFICATION_FAILED</td><td>Triggered when address ownership has failed verification.</td></tr></tbody></table>

## Webhook request schema

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

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

<details>

<summary><strong>Travel Rule data schema</strong></summary>

<table><thead><tr><th width="213">Name</th><th width="95.8564453125">Type</th><th width="349.3968505859375">Description</th></tr></thead><tbody><tr><td><code>transfer_id</code></td><td>UUIDV7</td><td>Unieuq identifier for the transfer.</td></tr><tr><td><code>reference_id</code></td><td>string</td><td><p>Identifier for the transfer, defined by the sender. </p><p></p><p>Example: <code>transfer20250312040414</code></p></td></tr><tr><td><code>amount</code></td><td>number</td><td>The amount of the digital token being transferred.</td></tr><tr><td><code>amount_usd</code></td><td>number</td><td>The value of the digital token being transferred in USD.</td></tr><tr><td><code>dti</code></td><td>string</td><td><p>The unique DTI reference of the digital token. </p><p></p><p>Refer to <a data-mention href="/pages/ATlQND59dM7SZDB793Cq">/pages/ATlQND59dM7SZDB793Cq</a> for the complete list of supported DTIs. </p><p></p><p>Example: <code>4H95J0R2X</code></p></td></tr><tr><td><code>chain</code></td><td>string</td><td><p>The chain name of the digital token. </p><p></p><p>Refer to <a data-mention href="/pages/ATlQND59dM7SZDB793Cq">/pages/ATlQND59dM7SZDB793Cq</a> for the complete list of supported chains. </p><p></p><p>Example: <mark style="color:orange;"><code>bitcoin</code></mark></p></td></tr><tr><td><code>symbol</code></td><td>string</td><td><p>The symbol of the digital token. </p><p></p><p>Refer to <a data-mention href="/pages/ATlQND59dM7SZDB793Cq">/pages/ATlQND59dM7SZDB793Cq</a> for the complete list of supported token symbols. </p><p></p><p>Example: <mark style="color:orange;"><code>BTC</code></mark></p></td></tr><tr><td><code>protocol</code></td><td>string</td><td><p>Travel Rule protocol used for the information exchange. <br><br>Examples: </p><ul><li>"flow"</li><li>"trp"</li><li>"trisa"</li><li>"gtr"</li></ul></td></tr><tr><td><code>transaction_hash</code></td><td>string</td><td>Blockchain transaction hash.</td></tr><tr><td><code>transfer_status</code></td><td>string</td><td>Refer to <a data-mention href="/pages/uUksnCah4UogljBjeXtG">/pages/uUksnCah4UogljBjeXtG</a> for the complete list of travel rule statuses.</td></tr></tbody></table>

</details>

<details>

<summary>Address Verification <strong>data schema</strong></summary>

<table><thead><tr><th width="213">Name</th><th width="95.8564453125">Type</th><th width="349.3968505859375">Description</th></tr></thead><tbody><tr><td><code>address</code></td><td>string</td><td>Unique blockchain identifier. <br><br>Example: <code>1JjYpRXfPntVEJqAjxsYmvFjjJBdJyaJ2k</code></td></tr><tr><td><code>chain</code></td><td>string</td><td>Blockchain network name. <br><br>Example: <code>bitcoin</code></td></tr><tr><td><code>is_validated</code></td><td>boolean</td><td>Indicates whether the address exists and has a transaction history.</td></tr><tr><td><code>is_self_hosted</code></td><td>boolean</td><td>Shows if the address has been labeled as self-hosted.</td></tr><tr><td><code>is_verified</code></td><td>boolean</td><td>Confirms if ownership has been cryptographically proven via a digital signature. </td></tr><tr><td><code>is_customer</code></td><td>boolean</td><td>Flags whether the address is associated with a known customer account. </td></tr><tr><td><code>reference_id</code></td><td>string</td><td>Internal reference ID of the associated account. </td></tr></tbody></table>

</details>

## Webhook request examples

#### **Travel Rule**&#x20;

**B**elow are example requests for the different travel rule events.

{% tabs fullWidth="false" %}
{% tab title="INCOMING\_TRANSFER" %}

```json
// 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
  }
}
```

{% endtab %}

{% tab title="TRANSFER\_ACCEPTED" %}

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

{% endtab %}

{% tab title="TRANSFER\_REJECTED" %}

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

{% endtab %}

{% tab title="TRANSFER\_REPAIR" %}

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

{% endtab %}

{% tab title="TRANSFER\_COMPLETED" %}

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

{% endtab %}

{% tab title="TRANSFER\_CANCELED" %}

```json
// 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",
    "transfer_type": "INSTRUCTION",
    "originator_address_is_self_hosted": true,
    "beneficiary_address_is_self_hosted": false
  }
}
```

{% endtab %}
{% endtabs %}

#### Address Verification

**B**elow are example requests for the different address verification events.

{% tabs fullWidth="false" %}
{% tab title="ADDRESS\_VERIFICATION\_COMPLETED" %}

```json
{
  "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
  }
}
```

{% endtab %}

{% tab title="ADDRESS\_VERIFICATION\_FAILED" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ospree.io/ospree-api/webhooks/webhook-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.