Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Shkola. With webhooks, your app can know when something happens in Shkola, such as an article being published or updated.

Registering Webhooks

To register a new webhook, you need to have a URL in your app that ShkolaFit can call. You can configure a new webhook from the Shkola dashboard under API settings. Give your webhook a name, choose the events you want to listen for, and add your webhook URL.

Now, whenever something of interest happens, a webhook will be triggered by ShkolaFit. In the next section, we’ll look at how to consume and process webhooks.

Consuming Webhooks

When your app receives a webhook request from ShkolaFit, check the type attribute to see what event caused the webhook to fire. The first part of the event type will indicate the payload type, such as an article or user data.

{
  "id": "a056V7R7NmNRjl70",
  "type": "article.created",
  "payload": {
    "id": "WAz8eIbvDR60rouK",
    "title": "Understanding Webhooks",
    "author": "John Doe",
    "published_at": "2025-01-22T12:00:00",
    "url": "https://example.com/articles/understanding-webhooks"
    // Other article data
  }
}

In the example above, the type article.created indicates that a new article was created, and the payload contains the details of the article.

Event types

{
  "id": "a056V7R7NmNRjl70",
  "type": "article.created",
  "payload": {
    "id": "WAz8eIbvDR60rouK",
    "title": "How Webhooks Work",
    "author": "Jane Doe",
    "published_at": "2025-01-22T12:00:00",
    "content": "Webhooks are a way for one system to send real-time data to another...",
    "url": "https://example.com/articles/how-webhooks-work"
  }
}

Security

To ensure that a webhook is truly coming from Shkola and not a malicious actor, you can verify the request signature. Each webhook request includes a header named x-shkola-signature, which you can use to verify the authenticity of the request by using your secret webhook key. The signature is an HMAC hash of the request payload, hashed using your secret key.

const signature = req.headers['x-shkola-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

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

If the generated signature matches the x-shkola-signature header, you can be sure that the request came from Shkola. It's crucial to keep your secret webhook key safe — if compromised, your system will no longer be able to verify the authenticity of the webhooks. Don’t commit your secret webhook key to GitHub or expose it publicly!

This should help you get started with registering and consuming webhooks with Shkola. If you need further assistance or have specific questions, feel free to reach out!