Webhooks API

Manage your webhooks programmatically: create, update, delete, subscribe to entities, and view delivery history.

Parameter

{id}Webhook ID (UUID)

Available endpoints

GET/api/v2/webhooks

List all webhooks

POST/api/v2/webhook

Create a webhook

GET/api/v2/webhook/{id}

Get webhook details

PUT/api/v2/webhook/{id}

Update webhook (name, URL, status)

DELETE/api/v2/webhook/{id}

Delete webhook

GET/api/v2/webhook/{id}/subscriptions

List watched entities

POST/api/v2/webhook/{id}/subscriptions

Add entities to watch

DELETE/api/v2/webhook/{id}/subscriptions

Remove watched entities

GET/api/v2/webhook/{id}/events

Delivery history (last 100)

PATCH/api/v2/webhook/{id}/hmac-secret

Rotate HMAC secret

POST/api/v2/webhook/{id}/trigger

Trigger test event

Request body (POST /webhook)

bash

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": "Production listener",
    "url": "https://hooks.example.com/companybelgium",
    "entityNumbers": ["1033022383", "0202239951"]
  }'

⚠️ The `hmacSecret` field is returned only once. Store it securely.

json

{
  "success": true,
  "data": {
    "id": "cl9abc123...",
    "name": "Production listener",
    "url": "https://hooks.example.com/companybelgium",
    "disabled": false,
    "hmacSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "createdAt": "2026-04-15T10:00:00.000Z"
  },
  "timestamp": "2026-04-15T10:00:00.000Z"
}

PUT /api/v2/webhook/{id}

bash

curl -X PUT https://companybelgium.be/api/v2/webhook/${WEBHOOK_ID} \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-API-Secret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production listener v2",
    "url": "https://hooks.example.com/v2/companybelgium",
    "disabled": false
  }'

Request body (POST/DELETE /subscriptions)

bash

# Ajouter des entités à surveiller
curl -X POST https://companybelgium.be/api/v2/webhook/${WEBHOOK_ID}/subscriptions \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-API-Secret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "entityNumbers": ["0417497106", "0403170701"]
  }'

# Retirer des entités
curl -X DELETE https://companybelgium.be/api/v2/webhook/${WEBHOOK_ID}/subscriptions \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-API-Secret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "entityNumbers": ["0417497106"]
  }'

GET /api/v2/webhook/{id}/events

bash

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

json

{
  "success": true,
  "data": [
    {
      "id": "evt_abc123...",
      "event": "update",
      "entityNumber": "1033022383",
      "entityType": "enterprise",
      "status": "delivered",
      "httpStatus": 200,
      "attempts": 1,
      "createdAt": "2026-04-15T09:30:00.000Z",
      "deliveredAt": "2026-04-15T09:30:01.000Z"
    },
    {
      "id": "evt_def456...",
      "event": "update",
      "entityNumber": "0202239951",
      "entityType": "enterprise",
      "status": "failed",
      "httpStatus": 503,
      "attempts": 3,
      "createdAt": "2026-04-15T08:00:00.000Z",
      "lastAttemptAt": "2026-04-15T08:00:10.000Z"
    }
  ],
  "timestamp": "2026-04-15T10:00:00.000Z"
}

PATCH /api/v2/webhook/{id}/hmac-secret

bash

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

json

{
  "success": true,
  "data": {
    "hmacSecret": "whsec_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  },
  "timestamp": "2026-04-15T10:00:00.000Z"
}

POST /api/v2/webhook/{id}/trigger

bash

curl -X POST https://companybelgium.be/api/v2/webhook/${WEBHOOK_ID}/trigger \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-API-Secret: ${API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "entityNumber": "1033022383",
    "data": {"note": "Manual test from dashboard"}
  }'

Integration guide

Swagger reference

Need help?

Our support team is available to help you with API integration.