Webhooks

Met webhooks ontvang je real-time notificaties wanneer er iets verandert in Boom. Ideaal voor het synchroniseren van je PIM, ERP, webshop of ander systeem zonder te hoeven pollen.

Een veelvoorkomend scenario: je hebt een PIM-systeem (Product Information Management) en wilt dat productwijzigingen in Boom automatisch worden doorgevoerd in je webshop. Met webhooks is dat in een middag gebouwd.

PIM-integratie in 3 stappen

Stel, je beheert je productcatalogus in Boom en wilt je webshop automatisch bijwerken wanneer een product wordt aangemaakt, gewijzigd of verwijderd. Zo werkt het:

1. Registreer een webhook voor product.created, product.updated en product.deleted events.

2. Ontvang notificaties — Boom stuurt een POST request naar je endpoint met het product als payload.

3. Synchroniseer — je webshop verwerkt de payload en werkt het product bij.

┌──────────┐    PUT /v1/products     ┌──────────┐    POST (webhook)     ┌──────────┐
│   PIM    │ ──────────────────────▶ │   API    │ ──────────────────── ▶│  Webshop │
│  Systeem │                         │          │                       │          │
└──────────┘                         └──────────┘                       └──────────┘

Het resultaat: je PIM is de single source of truth, Boom distribueert de wijzigingen, en je webshop is altijd up-to-date.

Registering webhooks

Registreer een webhook door een POST request te sturen naar /v1/webhooks met de events die je wilt ontvangen en de URL van je endpoint.

Required attributes

Name
notificationUrl
Type
string
Description
De URL waar Boom notificaties naartoe stuurt (HTTPS vereist).
Name
events
Type
string[]
Description
De events waarvoor je notificaties wilt ontvangen.

Request

POST

/v1/webhooks

curl https://api.example.nl/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationUrl": "https://mijn-webshop.nl/webhooks/products",
    "events": [
      "product.created",
      "product.updated",
      "product.deleted"
    ]
  }'

Response

{
  "id": "clx...",
  "notificationUrl": "https://mijn-webshop.nl/webhooks/products",
  "events": [
    "product.created",
    "product.updated",
    "product.deleted"
  ]
}

Consuming webhooks

Wanneer een event plaatsvindt, stuurt Boom een POST request naar je notificationUrl met een JSON payload. Controleer het type veld om te bepalen welk event het betreft.

Payload structuur

Name
id
Type
string
Description
Unieke identifier van de notificatie.
Name
type
Type
string
Description
Het event type, bijv. product.updated.
Name
timestamp
Type
string
Description
ISO 8601 timestamp van het event.
Name
payload
Type
object
Description
De volledige resource zoals deze er na de wijziging uitziet.

Je endpoint moet een 200 status code teruggeven om te bevestigen dat de notificatie is ontvangen. Bij een fout probeert Boom het maximaal 3 keer opnieuw met exponential backoff.

product.updated payload

{
  "id": "evt_a056V7R7NmNRjl70",
  "type": "product.updated",
  "timestamp": "2026-03-24T14:30:00.000Z",
  "payload": {
    "ean": "9789493113862",
    "name": "POLARIS nask1 leerwerkboek vmbo-basis 3 deel A",
    "price": "32.50",
    "type": "physical",
    "status": "available",
    "forSale": true,
    "updated": "2026-03-24T14:30:00.000Z"
  }
}

product.deleted payload

{
  "id": "evt_b167X8S8OnORslm81",
  "type": "product.deleted",
  "timestamp": "2026-03-24T15:00:00.000Z",
  "payload": {
    "ean": "9789493113862"
  }
}

Voorbeeld: webshop synchronisatie

Hieronder een minimaal voorbeeld van een webhook endpoint dat productwijzigingen verwerkt in je webshop:

Webhook handler

import express from 'express'

const app = express()
app.use(express.json())

app.post('/webhooks/products', async (req, res) => {
  const { type, payload } = req.body

  switch (type) {
    case 'product.created':
    case 'product.updated':
      await webshop.products.upsert({
        ean: payload.ean,
        name: payload.name,
        price: payload.price,
        available: payload.status === 'available',
      })
      break

    case 'product.deleted':
      await webshop.products.delete(payload.ean)
      break
  }

  res.sendStatus(200)
})

Event types

Product events

Name
product.created
Description
Een nieuw product is aangemaakt.
Name
product.updated
Description
Een bestaand product is bijgewerkt (prijs, status, naam, etc.).
Name
product.deleted
Description
Een product is verwijderd.

Order events

Name
order.created
Description
Een nieuwe verkooporder is aangemaakt.
Name
order.updated
Description
Een bestaande order is bijgewerkt (status, leverdatum, etc.).

Shipment events

Name
shipment.created
Description
Een nieuwe verzending is aangemaakt.
Name
shipment.updated
Description
Een verzending is bijgewerkt (track & trace, status, etc.).

Invoice events

Name
invoice.created
Description
Een nieuwe factuur is aangemaakt.
Name
invoice.updated
Description
Een factuur is bijgewerkt (status, etc.).

order.created payload

{
  "id": "evt_c278Y9T9PpPStmn92",
  "type": "order.created",
  "timestamp": "2026-03-24T16:00:00.000Z",
  "payload": {
    "id": "clx...",
    "number": "SO-106073",
    "customerId": "clx...",
    "status": "draft",
    "origin": "api",
    "orderDate": "2026-03-24T16:00:00.000Z",
    "lines": [
      {
        "productEan": "9789493113862",
        "quantity": 42,
        "price": "32.50"
      }
    ]
  }
}

Security

Om te verifiëren dat een webhook daadwerkelijk door Boom is verstuurd, bevat elk request een x-webhook-signature header. Dit is een HMAC-SHA256 hash van de request body, ondertekend met je webhook secret.

Signature verificatie

const signature = req.headers['x-webhook-signature']
const hash = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

Bewaar je webhook secret veilig en commit het nooit naar je repository.