Webhooks (Admin)

To start receiving commerce service webhooks in your application, you must first create some webhook configuration inside your company.

Basically, that configurations defines what is the endpoint that commerce service should call when some event happens and it defines also the signature key that the endpoint should use to validate the request.

To understand how to verify webhook signatures and what are the available webhook events, please visit Webhooks Page.

Webhook Configuration Model (Example)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2022-11-04T13:36:47.665Z",
  "updatedAt": "2022-11-04T13:36:47.665Z",
  "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "company": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2022-11-04T13:36:47.665Z",
    "updatedAt": "2022-11-04T13:36:47.665Z",
    "name": "string"
  },
  "webhookUrl": "https://mydomain.hook.me",
  "signatureKey": "string",
  "maxRetries": 5,
  "disabled": false
}

Service Methods

Creates a new Webhook Configuration inside a company

The signature key could not be changed and is automatically generated. Each configuration has it owns signature key. To be safe, you must ensure that your endpoint will accept request only from our service by checking the signature.

Rest API reference:

post

Creates a new company webhooks configuration

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

Body

application/json

webhookUrlstringRequiredExample: https://w3block.io/webhooks/test

maxRetriesnumberOptionalDefault: 5Example: 5

Responses

201Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

post

/admin/companies/{companyId}/webhooks-configurations

HTTPcURLJavaScriptPython

POST /admin/companies/{companyId}/webhooks-configurations HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "webhookUrl": "https://w3block.io/webhooks/test",
  "maxRetries": 5
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-11-05T16:46:40.427Z",
  "updatedAt": "2025-11-05T16:46:40.427Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-11-05T16:46:40.427Z",
    "updatedAt": "2025-11-05T16:46:40.427Z",
    "name": "text"
  },
  "webhookUrl": "https://mydomain.hook.me",
  "signatureKey": "text",
  "maxRetries": 5,
  "disabled": false
}

Lists all webhook configurations from some company

Rest API reference:

get

Lists all company webhooks configurations

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

Query parameters

pagenumberOptionalDefault: 1

limitnumberOptionalDefault: 10

searchstringOptional

sortBystringOptional

orderBystring · enumOptionalPossible values:

Responses

200Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

get

/admin/companies/{companyId}/webhooks-configurations

HTTPcURLJavaScriptPython

GET /admin/companies/{companyId}/webhooks-configurations HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-11-05T16:46:40.427Z",
      "updatedAt": "2025-11-05T16:46:40.427Z",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "createdAt": "2025-11-05T16:46:40.427Z",
        "updatedAt": "2025-11-05T16:46:40.427Z",
        "name": "text"
      },
      "webhookUrl": "https://mydomain.hook.me",
      "signatureKey": "text",
      "maxRetries": 5,
      "disabled": false
    }
  ],
  "meta": {
    "itemCount": 1,
    "totalItems": 1,
    "itemsPerPage": 1,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "first": "http://example.com?page=1",
    "prev": "http://example.com?page=1",
    "next": "http://example.com?page=2",
    "last": "http://example.com?page=3"
  }
}

Gets some webhook configuration of a company by ID

Rest API reference:

get

Gets some company webhooks configuration

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

Responses

200Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

get

/admin/companies/{companyId}/webhooks-configurations/{configurationId}

HTTPcURLJavaScriptPython

GET /admin/companies/{companyId}/webhooks-configurations/{configurationId} HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-11-05T16:46:40.427Z",
  "updatedAt": "2025-11-05T16:46:40.427Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-11-05T16:46:40.427Z",
    "updatedAt": "2025-11-05T16:46:40.427Z",
    "name": "text"
  },
  "webhookUrl": "https://mydomain.hook.me",
  "signatureKey": "text",
  "maxRetries": 5,
  "disabled": false
}

Updates some company webhook configuration

Rest API reference:

patch

Updates some company webhooks configuration

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

Body

application/json

webhookUrlstringRequiredExample: https://w3block.io/webhooks/test

maxRetriesnumberOptionalDefault: 5Example: 5

Responses

200Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

patch

/admin/companies/{companyId}/webhooks-configurations/{configurationId}

HTTPcURLJavaScriptPython

PATCH /admin/companies/{companyId}/webhooks-configurations/{configurationId} HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "webhookUrl": "https://w3block.io/webhooks/test",
  "maxRetries": 5
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-11-05T16:46:40.427Z",
  "updatedAt": "2025-11-05T16:46:40.427Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-11-05T16:46:40.427Z",
    "updatedAt": "2025-11-05T16:46:40.427Z",
    "name": "text"
  },
  "webhookUrl": "https://mydomain.hook.me",
  "signatureKey": "text",
  "maxRetries": 5,
  "disabled": false
}

Enables some disabled company webhook configuration

Rest API reference:

patch

Enables some company webhooks configuration

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

Responses

204Success

No content

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

patch

/admin/companies/{companyId}/webhooks-configurations/{configurationId}/enable

HTTPcURLJavaScriptPython

PATCH /admin/companies/{companyId}/webhooks-configurations/{configurationId}/enable HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Disabled some enabled company webhook configuration

Rest API reference:

patch

Disables some company webhooks configuration

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

Responses

204Success

No content

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

patch

/admin/companies/{companyId}/webhooks-configurations/{configurationId}/disable

HTTPcURLJavaScriptPython

PATCH /admin/companies/{companyId}/webhooks-configurations/{configurationId}/disable HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Lists all events sent by some webhook configuration

With that sent webhook event entity, you can also know the result of the request and the last result that your configured endpoint returned to the commerce service.

Rest API reference:

get

Lists all webhooks sent using some webhooks configuration of company

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

Query parameters

pagenumberOptionalDefault: 1

limitnumberOptionalDefault: 10

searchstringOptional

sortBystringOptional

orderBystring · enumOptionalPossible values:

Responses

200Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

get

/admin/companies/{companyId}/webhooks-configurations/{configurationId}/webhooks

HTTPcURLJavaScriptPython

GET /admin/companies/{companyId}/webhooks-configurations/{configurationId}/webhooks HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-11-05T16:46:40.427Z",
      "updatedAt": "2025-11-05T16:46:40.427Z",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "createdAt": "2025-11-05T16:46:40.427Z",
        "updatedAt": "2025-11-05T16:46:40.427Z",
        "name": "text"
      },
      "configurationId": "123e4567-e89b-12d3-a456-426614174000",
      "configuration": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "createdAt": "2025-11-05T16:46:40.427Z",
        "updatedAt": "2025-11-05T16:46:40.427Z",
        "companyId": "123e4567-e89b-12d3-a456-426614174000",
        "company": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdAt": "2025-11-05T16:46:40.427Z",
          "updatedAt": "2025-11-05T16:46:40.427Z",
          "name": "text"
        },
        "webhookUrl": "https://mydomain.hook.me",
        "signatureKey": "text",
        "maxRetries": 5,
        "disabled": false
      },
      "status": "concluded",
      "errors": 0,
      "data": false,
      "lastResult": null,
      "usePatch": false,
      "updateWithSystemHeaders": false,
      "addCreatedAtToBody": false
    }
  ],
  "meta": {
    "itemCount": 1,
    "totalItems": 1,
    "itemsPerPage": 1,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "first": "http://example.com?page=1",
    "prev": "http://example.com?page=1",
    "next": "http://example.com?page=2",
    "last": "http://example.com?page=3"
  }
}

Gets some webhook event sent by some webhook configuration by ID

Rest API reference:

get

Gets some company webhooks configuration sent webhook

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

configurationIdstringRequired

webhookIdstringRequired

Responses

200Success

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

get

/admin/companies/{companyId}/webhooks-configurations/{configurationId}/webhooks/{webhookId}

HTTPcURLJavaScriptPython

GET /admin/companies/{companyId}/webhooks-configurations/{configurationId}/webhooks/{webhookId} HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-11-05T16:46:40.427Z",
  "updatedAt": "2025-11-05T16:46:40.427Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-11-05T16:46:40.427Z",
    "updatedAt": "2025-11-05T16:46:40.427Z",
    "name": "text"
  },
  "configurationId": "123e4567-e89b-12d3-a456-426614174000",
  "configuration": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-11-05T16:46:40.427Z",
    "updatedAt": "2025-11-05T16:46:40.427Z",
    "companyId": "123e4567-e89b-12d3-a456-426614174000",
    "company": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-11-05T16:46:40.427Z",
      "updatedAt": "2025-11-05T16:46:40.427Z",
      "name": "text"
    },
    "webhookUrl": "https://mydomain.hook.me",
    "signatureKey": "text",
    "maxRetries": 5,
    "disabled": false
  },
  "status": "concluded",
  "errors": 0,
  "data": false,
  "lastResult": null,
  "usePatch": false,
  "updateWithSystemHeaders": false,
  "addCreatedAtToBody": false
}