# 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: 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://btpaydocs.blackthornfs.com/reference/api-reference/webhooks.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.