Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Studiewinkel. With webhooks, your app can know when something happens in Studiewinkel, such as someone publishing a list or adding a school.

Registering webhooks

To subscribe to a webhook, you need to have a URL in your app that Studiewinkel can call. You can use the Studiewinkel Lml API to create a new subscription.

curl
--location
--request POST 'https://lml-api.studiewinkel.nl/api/lml/v1/subscriptions'
  --header 'Authorization: Bearer ey...'
  --header 'Content-Type: application/json'
  --data-raw {
    "notificationUrl": https://<yourdomain>.com/logger,
    "event": "list-published"
  }

Now, whenever something of interest happens in your app, a webhook is fired off by Studiewinkel. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from Studiewinkel, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a school, list, etc.

{
  "type": "published",
  "resource": "list",
  "identifier": "1a2d1c669b0811ed840606955cf36fa4"
}

In the example above, a list was published, the payload type is a published and the resource is a list.

Event types

Security

To know for sure that a webhook was, in fact, sent by Studiewinkel instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-hook-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

const CryptoJS = require('crypto-js');

const generateHash = (payload, secret) => {
  const hash = CryptoJS.HmacSHA256(payload, secret);
  return CryptoJS.enc.Base64.stringify(hash);
}

...

const theirSignature = event.headers['x-hook-signature'];
const expectedSignature = generateHash(event.body, <yourwebhooksecret>);
if (theirSignature !== expectedSignature) {
  console.error('unauthorized api call. x-hook-signature does not match.');
}

If your generated signature matches the x-hook-signature header, you can be sure that the request was truly coming from Studiewinkel. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Studiewinkel.