> For the complete documentation index, see [llms.txt](https://docs.volven.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.volven.io/api/tyr-markets-api/webhook-notifications.md).

# Webhook notifications

For users who have been registered through a Partner, webhook notifications are sent instead of standard emails. These notifications are sent to a URL provided by the Partner. It is the Partner's responsibility to notify end-users in response to webhook notifications. TÝR Markets will never contact the Partner's users by email, even when sending mass emails (e.g. newsletter, announcements, T\&C updates, etc.).

All notifications will be sent using the following format:

```http
POST <<Webhook URL>>
Content-Type: application/json
X-Webhook-Timestamp: <<Request timestamp>>
X-Webhook-Signature: <<HMAC signature of the request>>
{
  "notificationId": "<<UUID>>",
  "notificationType": "<<notification type>>"
  <<Notification specific fields>>
}
```

For example:

```http
POST https://partner-site.com/tyr-markets-notifications
Content-Type: application/json
X-Webhook-Timestamp: 1787142319072
X-Webhook-Signature: Cb89j6Uofh+ka5ZlwcDw/nam/ib3YlZOkJhT54WiSR0=
{
  "notificationId": "15bc83d1-a298-41fb-a157-bae64b04d47e",
  "notificationType": "DEPOSIT_CONFIRMED",
  "volvenUserId": "7647",
  "transferId": "11950943-12d0-4d5a-b022-2fb2d8ee2406",
  "source": "9GpHcZdNGJ28XaYPg31s6km63TnJx6qu2JDoyknMXtL1",
  "currency": "SOL",
  "amount": "32.6479599"
}
```

{% hint style="info" %}
All notification payloads contain a unique `notificationId` field that might be used as an idempotency check. In some cases (network timeout, client mistakenly returning non success HTTP response code) a single notification can be delivered multiple times to the client.
{% endhint %}

{% hint style="info" %}
All notification payloads contain a `notificationType` field identifying the type of notification. Partners should use this field to determine how to process the notification.
{% endhint %}

{% hint style="warning" %}
Additional fields may be added to notification payloads in the future. Partners should ignore fields they do not recognise.
{% endhint %}

#### Body

The request body is a JSON object encoded as UTF-8.

#### Headers

Following HTTP headers will be present in every webhook notification:

* `X-Webhook-Timestamp` - request timestamp (Unix epoch milliseconds)\
  Partners should verify that the timestamp is within a short time window of the current time (e.g. 15 seconds) to protect against replay attacks.
* `X-Webhook-Signature` - HMAC-SHA256 signature of the request, encoded using Base64

  It is calculated in following way:

  1. Prepare canonical request by concatenating `X-Webhook-Timestamp` header value and raw HTTP request body, for example: `1787142319072{"notificationType":"DEPOSIT_CONFIRMED",...}`
  2. Sign canonical request with Partner's API Secret using HMAC-SHA256 algorithm
  3. Encode the signature in Base64 format.

  Partners should verify the signature to ensure that request comes from TÝR Markets.

{% hint style="info" %}
The Partner API Secret used for webhook signature verification is the same API Secret associated with the Partner’s API Key.
{% endhint %}

#### Response

TÝR Markets will do following action based on the HTTP response code from the Partner:

* 200 - 299: mark the notification as delivered
* any other status code: mark the notification delivery as failed
* timeout / network error: mark the notification delivery as failed (may result with same notification being sent more than once, `notificationId` should be used to detect duplicates)

In case of failed delivery TÝR Markets will retry sending notification to the Partner with linearly increasing backoff, starting with 1 minute and maximum of 100 attempts.

{% hint style="info" %}
Note that response headers and body will be ignored
{% endhint %}

#### Notification types

The following notification types are currently supported:

<details>

<summary>User successfully created</summary>

```json
{
  "notificationType": "USER_CREATED",
  "volvenUserId": "7647",
  "email": "user@domain.com"
}
```

</details>

<details>

<summary>User registration failed</summary>

```json
{
  "notificationType": "SIGNUP_FAILED",
  "email": "user@domain.com",
  "errorMessage": "Error details"
}
```

</details>

<details>

<summary>Deposit confirmed</summary>

```json
{
  "notificationType": "DEPOSIT_CONFIRMED",
  "volvenUserId": "7647",
  "transferId": "11950943-12d0-4d5a-b022-2fb2d8ee2406",
  "source": "9GpHcZdNGJ28XaYPg31s6km63TnJx6qu2JDoyknMXtL1",
  "currency": "SOL",
  "amount": "32.6479599"
}
```

</details>

<details>

<summary>Withdrawal confirmed</summary>

```json
{
  "notificationType": "WITHDRAWAL_CONFIRMED",
  "volvenUserId": "7647",
  "transferId": "11950943-12d0-4d5a-b022-2fb2d8ee2406",
  "target": "9GpHcZdNGJ28XaYPg31s6km63TnJx6qu2JDoyknMXtL1",
  "currency": "SOL",
  "amount": "32.6479599"
}
```

</details>

<details>

<summary>Withdrawal failed</summary>

```json
{
  "notificationType": "WITHDRAWAL_FAILED",
  "volvenUserId": "7647",
  "transferId": "11950943-12d0-4d5a-b022-2fb2d8ee2406",
  "target": "9GpHcZdNGJ28XaYPg31s6km63TnJx6qu2JDoyknMXtL1",
  "currency": "SOL",
  "amount": "32.6479599"
}
```

</details>

<details>

<summary>Withdrawal canceled</summary>

```json
{
  "notificationType": "WITHDRAWAL_CANCELED",
  "volvenUserId": "7647",
  "transferId": "11950943-12d0-4d5a-b022-2fb2d8ee2406",
  "target": "9GpHcZdNGJ28XaYPg31s6km63TnJx6qu2JDoyknMXtL1",
  "currency": "SOL",
  "amount": "32.6479599"
}
```

</details>

{% hint style="warning" %}
New notification types may be introduced in the future. Partners must ignore notification types they do not recognise.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.volven.io/api/tyr-markets-api/webhook-notifications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.