> For the complete documentation index, see [llms.txt](https://btpaydocs.blackthornfs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://btpaydocs.blackthornfs.com/reference/api-reference/webhooks.md).

# Webhooks

You can 'listen' for events that occur in your workspace at your chosen URL, where all event types will be broadcasted.

> **Webhook URL requirement:**
>
> Each webhook URL must be a complete, globally available HTTPS address (e.g., `https:// example.com`).

Events are sent to your webhook endpoint URL associated with the workspace, as part of a POST request with a JSON payload.

#### Webhook types:

There are 4 webhook types:

<details>

<summary>Received</summary>

**The Received webhook** will be sent when the payment process is started and transaction is found in a blockchain. This message is for informational purposes only and can be ignored.&#x20;

The Received webhook payload example:

```json
{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETHETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": null,
		"quoteCurrency": "USDT_TRX",
		"status": "Received",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Received",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}
```

</details>

<details>

<summary>Confirmed</summary>

**The Confirmed webhook** will be sent when the transaction is confirmed in a blockchain.

The Confirmed webhook payload example:

```json
{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": null,
		"quoteCurrency": "USDT_TRX",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}
```

</details>

<details>

<summary>Completed</summary>

**The Completed webhook** will be sent when the payment process is completed, but not settled yet.&#x20;

The Received webhook payload example:

```json
{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": 5500,
		"quoteCurrency": "USDT_TRX",
		"status": "Completed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}
```

</details>

<details>

<summary>Settled</summary>

**The Settled webhook** will be sent when the payment process is completed, funds are settled and available to withdraw.

The Settled webhook payload example:

```json
{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": 5500,
		"quoteCurrency": "USDT_TRX",
		"status": "Settled",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}
```

</details>

#### Verifying the signature of incoming webhooks

An incoming webhook request has a header that should be used to verify the payload has not been tampered with.&#x20;

The name of the header containing the signature - "**Signature**". The webhook is sent by a POST request, which contains JSON payload.&#x20;

```
$computedSignature = hash_hmac('sha256', $payloadJson, $secret);
```

If the computedSignature and received signature does match return 200 http code after processing the payload.&#x20;

If your server is temporarily unavailable or the status of the response is different from 200, we will resend the webhook several times with the increasing delay time.


---

# 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 dynamically by asking a question.

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

```
GET https://btpaydocs.blackthornfs.com/reference/api-reference/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.