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