Webhooks

Endpoints for the Webhooks resource. All calls require authentication and return the standard JSON envelope.

🔗

Base URL: https://companybelgium.be/api/v2 · Authentication

List all webhooks#

GET/webhooks

Every webhook registered for the authenticated company.

This endpoint takes no parameters.

Request

curl https://companybelgium.be/api/v2/webhooks \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhooks", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": [
    {
      "id": "wh_1a2b",
      "name": "Prod listener",
      "url": "https://example.be/hooks/bce",
      "disabled": false
    }
  ],
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Create a webhook#

POST/webhook

Registers an outbound webhook. The HMAC signing secret is returned only once, in this response — store it securely.

Request body

{
  "name": "Prod listener",
  "url": "https://example.be/hooks/bce",
  "entityNumbers": [
    "0403.170.701"
  ]
}

Request

curl -X POST https://companybelgium.be/api/v2/webhook \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Prod listener","url":"https://example.be/hooks/bce","entityNumbers":["0403.170.701"]}'

const res = await fetch("https://companybelgium.be/api/v2/webhook", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name":"Prod listener","url":"https://example.be/hooks/bce","entityNumbers":["0403.170.701"]}),
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "id": "wh_1a2b",
    "name": "Prod listener",
    "url": "https://example.be/hooks/bce",
    "hmacSecret": "whsec_8f3...redacted",
    "disabled": false
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Retrieve a webhook#

GET/webhook/{id}

A single webhook by id.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl https://companybelgium.be/api/v2/webhook/wh_1a2b \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "id": "wh_1a2b",
    "name": "Prod listener",
    "url": "https://example.be/hooks/bce",
    "disabled": false
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Update a webhook#

PUT/webhook/{id}

Update name, url or disabled flag.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request body

{
  "name": "Prod listener (paused)",
  "disabled": true
}

Request

curl -X PUT https://companybelgium.be/api/v2/webhook/wh_1a2b \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Prod listener (paused)","disabled":true}'

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b", {
  method: "PUT",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name":"Prod listener (paused)","disabled":true}),
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "id": "wh_1a2b",
    "name": "Prod listener (paused)",
    "disabled": true
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Delete a webhook#

DELETE/webhook/{id}

Deletes the webhook and cascades its subscriptions and delivery events.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl -X DELETE https://companybelgium.be/api/v2/webhook/wh_1a2b \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "deleted": true
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Rotate the HMAC signing secret#

PATCH/webhook/{id}/hmac-secret

Generates a new HMAC secret, returned only once. The old secret stops being valid immediately.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl -X PATCH https://companybelgium.be/api/v2/webhook/wh_1a2b/hmac-secret \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/hmac-secret", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "id": "wh_1a2b",
    "hmacSecret": "whsec_new...redacted"
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Send a test delivery#

POST/webhook/{id}/trigger

Manually triggers a test event so you can verify your endpoint and signature handling.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl -X POST https://companybelgium.be/api/v2/webhook/wh_1a2b/trigger \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/trigger", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "delivered": true,
    "eventId": "evt_test_001"
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

List subscribed entity numbers#

GET/webhook/{id}/subscriptions

Entity numbers this webhook is subscribed to.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": [
    "0403.170.701",
    "0738.916.702"
  ],
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Add entity subscriptions#

POST/webhook/{id}/subscriptions

Subscribe the webhook to one or more enterprise/establishment numbers.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request body

{
  "entityNumbers": [
    "0738.916.702"
  ]
}

Request

curl -X POST https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"entityNumbers":["0738.916.702"]}'

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"entityNumbers":["0738.916.702"]}),
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "added": 1
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Remove entity subscriptions#

DELETE/webhook/{id}/subscriptions

Unsubscribe the webhook from given entity numbers.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request body

{
  "entityNumbers": [
    "0738.916.702"
  ]
}

Request

curl -X DELETE https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"entityNumbers":["0738.916.702"]}'

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/subscriptions", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"entityNumbers":["0738.916.702"]}),
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": {
    "removed": 1
  },
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}

Delivery log#

GET/webhook/{id}/events

The last 100 delivery attempts with status, response code and timestamp.

Parameters

Name	In/Type	Required	Description
`id`	path string	Required	Webhook id.

Request

curl https://companybelgium.be/api/v2/webhook/wh_1a2b/events \
  -H "X-API-Key: $API_KEY" -H "X-API-Secret: $API_SECRET"

const res = await fetch("https://companybelgium.be/api/v2/webhook/wh_1a2b/events", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "X-API-Secret": process.env.API_SECRET,
  },
});
const { data } = await res.json();

Response

{
  "success": true,
  "data": [
    {
      "eventId": "evt_001",
      "status": "delivered",
      "responseCode": 200,
      "at": "2026-06-05T09:00:00Z"
    }
  ],
  "error": null,
  "timestamp": "2026-06-05T09:00:00.000Z",
  "meta": null
}