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

Order Creation

{
  "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
}

Order Concluded

{
  "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
}

Order Failed

{
  "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
}

Order Expired

{
  "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
}

Order Cancelled

{
  "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
}