# Webhooks

Commerce service can notify your application about some kind of events that happens inside your company tenant. To notify your application, we use the pattern of REST Webhooks.

To start receiving our webhooks, you must first [create a webhook configuration inside your company](/w3block-eng/dev-docs/api/commerce-api-services/company-administration/webhooks-admin.md). Since your company has one webhook configuration enabled, you will start receiving our webhook events.

## Webhook Authentication

All of our webhooks are signed to confirm that your application is receiving a true webhook. This signature is sent in the request header named **`x-w3block-commerce-signature`**.

To verify the signature follow the steps:

1. Compute a HMAC with the SHA-256 hash function of the request payload. Use your webhook configuration signature key in the signature creation.
2. Compare the signature in the header to the expected signature.

## Available Webhooks

### Orders

We can notify all of order events like creation and status changes to your application. See some examples above:

{% tabs %}
{% tab title="Order Creation" %}

```json
{
  "data": {
    "id": "8e29703b-3706-466a-ba14-cd12749c9dcc",
    "gasFee": "0.020621829275431147",
    "status": "pending",
    "userId": "7cbd6b95-0247-40b3-a9e9-2ea9b6195cb0",
    "addressId": null,
    "companyId": "010e92ea-d3af-40d9-a19e-a263fdfe6e92",
    "createdAt": "2022-10-19T17:51:14.148Z",
    "expiresIn": "2022-10-20T03:51:14.677Z",
    "updatedAt": "2022-10-19T17:51:14.148Z",
    "currencyId": "8c43ece8-99b0-4877-aed3-2170d2deb4bf",
    "serviceFee": "0",
    "deliverDate": null,
    "paymentInfo": {
      "publicKey": "pk_test_51LXlkcLjgooBZGqLtsJOxvWAUODRl8PDeg8hFtousHL1pA0iqW73fmXweqYO67XzG0pn50YmnFT0cBTTKzCEYSWa00XRYaEiyf",
      "clientSecret": "pi_3LugQALjgooBZGqL1Gi6RFTP_secret_RsR2M9xPwQTKcV3M9aKe51zSl"
    },
    "paymentMethod": null,
    "currencyAmount": "1.2",
    "paymentProvider": "stripe",
    "providerTransactionId": "pi_3LugQALjgooBZGqL1Gi6RFTP",
    "destinationWalletAddress": "0xe28eac8f542d0dd11a706f08d1953dd4c2ff07ab"
  },
  "event": "order.created",
  "timestamp": 1666201874688
}
```

{% endtab %}

{% tab title="Order Concluded" %}

```json
{
  "data": {
    "id": "8e29703b-3706-466a-ba14-cd12749c9dcc",
    "gasFee": "0.020621829275431147",
    "status": "concluded",
    "userId": "7cbd6b95-0247-40b3-a9e9-2ea9b6195cb0",
    "addressId": null,
    "companyId": "010e92ea-d3af-40d9-a19e-a263fdfe6e92",
    "createdAt": "2022-10-19T17:51:14.148Z",
    "expiresIn": "2022-10-20T03:51:14.677Z",
    "updatedAt": "2022-10-19T17:58:01.719Z",
    "currencyId": "8c43ece8-99b0-4877-aed3-2170d2deb4bf",
    "deliverDate": "2022-10-19T17:54:00.961Z",
    "paymentInfo": {
      "publicKey": "pk_test_51LXlkcLjgooBZGqLtsJOxvWAUODRl8PDeg8hFtousHL1pA0iqW73fmXweqYO67XzG0pn50YmnFT0cBTTKzCEYSWa00XRYaEiyf",
      "clientSecret": "pi_3LugQALjgooBZGqL1Gi6RFTP_secret_RsR2M9xPwQTKcV3M9aKe51zSl"
    },
    "paymentMethod": null,
    "currencyAmount": "1.2",
    "paymentProvider": "stripe",
    "clientServiceFee": "0",
    "providerTransactionId": "pi_3LugQALjgooBZGqL1Gi6RFTP",
    "destinationWalletAddress": "0xe28eac8f542d0dd11a706f08d1953dd4c2ff07ab"
  },
  "event": "order.concluded",
  "timestamp": 1666202281780
}
```

{% endtab %}

{% tab title="Order Failed" %}

```json
{
  "data": {
    "id": "f090722e-3349-43f4-a78d-7670756cb1f2",
    "gasFee": "0.012096888715549192",
    "status": "failed",
    "userId": "a68d7d77-4848-48dc-9bb4-b72aca32ff92",
    "addressId": null,
    "companyId": "010e92ea-d3af-40d9-a19e-a263fdfe6e92",
    "createdAt": "2022-10-17T19:52:20.009Z",
    "expiresIn": "2022-10-18T05:52:20.654Z",
    "updatedAt": "2022-10-17T19:56:03.741Z",
    "currencyId": "8c43ece8-99b0-4877-aed3-2170d2deb4bf",
    "serviceFee": "0",
    "deliverDate": "2022-10-17T19:55:01.379Z",
    "paymentInfo": {
      "publicKey": "pk_test_51LXlkcLjgooBZGqLtsJOxvWAUODRl8PDeg8hFtousHL1pA0iqW73fmXweqYO67XzG0pn50YmnFT0cBTTKzCEYSWa00XRYaEiyf",
      "clientSecret": "pi_3LtzMGLjgooBZGqL0kUP3i8s_secret_2rCD8aEoeoJeMVdxW23MWNBT9"
    },
    "paymentMethod": null,
    "currencyAmount": "50",
    "paymentProvider": "stripe",
    "providerTransactionId": "pi_3LtzMGLjgooBZGqL0kUP3i8s",
    "destinationWalletAddress": "0xa4fa840ea696dd3649f271e43fe82c3c84ce546a"
  },
  "event": "order.failed",
  "timestamp": 1666036563750
}
```

{% endtab %}

{% tab title="Order Expired" %}

```json
{
  "data": {
    "id": "890a49d1-dc4e-4ee2-b595-a9f19710a927",
    "gasFee": "0.009907688016363445",
    "status": "expired",
    "userId": "f01a6ba4-fe71-4541-acdb-469ece12deaf",
    "addressId": null,
    "companyId": "010e92ea-d3af-40d9-a19e-a263fdfe6e92",
    "createdAt": "2022-10-18T21:19:35.884Z",
    "expiresIn": "2022-10-19T07:19:36.336Z",
    "updatedAt": "2022-10-18T21:19:35.884Z",
    "currencyId": "8c43ece8-99b0-4877-aed3-2170d2deb4bf",
    "serviceFee": "0",
    "deliverDate": null,
    "paymentInfo": {
      "publicKey": "pk_test_51LXlkcLjgooBZGqLtsJOxvWAUODRl8PDeg8hFtousHL1pA0iqW73fmXweqYO67XzG0pn50YmnFT0cBTTKzCEYSWa00XRYaEiyf",
      "clientSecret": "pi_3LuNCGLjgooBZGqL2d3ZCF1z_secret_gFbZDyRGYkiINP7JoDyi9SdmP"
    },
    "paymentMethod": null,
    "currencyAmount": "1.1",
    "paymentProvider": "stripe",
    "providerTransactionId": "pi_3LuNCGLjgooBZGqL2d3ZCF1z",
    "destinationWalletAddress": "0x3f66899a7db70d6438ef1855ea2b1d2591c2df87"
  },
  "event": "order.expired",
  "timestamp": 1666170230650
}
```

{% endtab %}

{% tab title="Order Cancelled" %}

```json
{
  "data": {
    "id": "890a49d1-dc4e-4ee2-b595-a9f19710a927",
    "gasFee": "0.009907688016363445",
    "status": "cancelled",
    "userId": "f01a6ba4-fe71-4541-acdb-469ece12deaf",
    "addressId": null,
    "companyId": "010e92ea-d3af-40d9-a19e-a263fdfe6e92",
    "createdAt": "2022-10-18T21:19:35.884Z",
    "expiresIn": "2022-10-19T07:19:36.336Z",
    "updatedAt": "2022-10-18T21:19:35.884Z",
    "currencyId": "8c43ece8-99b0-4877-aed3-2170d2deb4bf",
    "serviceFee": "0",
    "deliverDate": null,
    "paymentInfo": {
      "publicKey": "pk_test_51LXlkcLjgooBZGqLtsJOxvWAUODRl8PDeg8hFtousHL1pA0iqW73fmXweqYO67XzG0pn50YmnFT0cBTTKzCEYSWa00XRYaEiyf",
      "clientSecret": "pi_3LuNCGLjgooBZGqL2d3ZCF1z_secret_gFbZDyRGYkiINP7JoDyi9SdmP"
    },
    "paymentMethod": null,
    "currencyAmount": "1.1",
    "paymentProvider": "stripe",
    "providerTransactionId": "pi_3LuNCGLjgooBZGqL2d3ZCF1z",
    "destinationWalletAddress": "0x3f66899a7db70d6438ef1855ea2b1d2591c2df87"
  },
  "event": "order.cancelled",
  "timestamp": 1666170230650
}
```

{% 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://w3block.gitbook.io/w3block-eng/dev-docs/api/commerce-api-services/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.