Managing webhooks in SchoolMind

What is a webhook?

In short, webhook is a way for an app to provide other applications with real-time information. When an event happens (e.g. student is added in SchoolMind), a webhook delivers that data to other applications as it happens. So, we can call it a "service" which notifies that some data is sent from an app to other applications. 

Considering the above said, SchoolMind can notify your application of events using webhooks. Each hook is cryptographically signed, so the request cannot be tampered with. If you receive a webhook, you can validate it to make sure it comes from us.

When working with webhooks in SchoolMind, please consider the following:

• A maximum number of 5 webhooks can be created.

• We support HTTP and HTTPS (invalid SSL certificates will be rejected).

• Webhooks are server wide, and cannot be used only for a single institution.

How webhooks work

Every event we fire internally will also be translated to the webhook URL you provide in your webhook settings.

This means you can receive the raw payload of events like new employee added or updated, the new student added or updated...you name it. You can then use that information to update internal systems, keep internal audit logs, etc.

Authentication

All the webhooks we send will be signed by a signing secret. You can create the signing secret for each webhook. You don't have to validate the incoming request, but it's highly suggested.

Webhook authentication & signing

Our signing method is simple but efficient. For every webhook we call, we pass an additional header called SchoolMind-Signature that contains the hash of the payload.

In your webhook, you can validate if that SchoolMind-Signature header contains the hash you expected.

A sample PHP script to accept JSON requests:

<?php
$raw_content = file_get_contents("php://input");
$secret = "matching_secret";
$schoolmind_signature = $_SERVER['HTTP_X_SCHOOLMIND_SIGNATURE'];
$data = json_decode($raw_content, true);
// $data['payload']['first_name']; // First name
$local_signature = strtoupper(hash_hmac('sha256', $raw_content, $secret));
if (hash_equals($local_signature, $schoolmind_signature)) {
   //"Signature valid!";
} else {
   // "Signature not valid!";
}

A sample PHP script to accept FORM requests:

<?php
$raw_content = file_get_contents("php://input");
$secret = "matching_secret";
$schoolmind_signature = $_SERVER['HTTP_X_SCHOOLMIND_SIGNATURE'];
$data = json_decode($_POST['payload'], true);
// $data['first_name']; // First name
$local_signature = strtoupper(hash_hmac('sha256', $raw_content, $secret));
if (hash_equals($local_signature, $schoolmind_signature)) {
   //"Signature valid!";
} else {
   // "Signature not valid!";
}

Adding a new webhook

To add a webhook in SchoolMind:

1. Navigate to the System > Manage Webhooks > Add New.
2. Enter your Payload URL.
3. Select the Content Type whether it's a JSON or a FORM (see examples above).
4. Enter the Secret.
5. Select for which events the webhook will be triggered. Choose between all and selected events.
6. Click the Save button.

Once your webhook is configured, we'll call it for every event we fire and you will get the raw payload and can act on it as you see fit.

Webhook retries

If we receive an HTTP/200 from your webhook URL, we consider the webhook successful. If your application returns anything else, including 301 or 302 redirects, we mark the webhook as failed and won't resend the same payload again.

Shall you need to resend a failed delivery, click on Actions > View Deliveries next to your payload, and you will get the list of the recent deliveries.

To resend any delivery from the list, simply click Details > Resend > Yes.

For each delivery, when you click on Details button, there are delivery details where you can see the completion time, request headers, request payload, response headers, response body, and response error.

Setting a webhook as inactive (disabling a webhook)

If for any reason you don't want to use the webhook anymore, instead of deleting it, you can set it as inactive. To do that:

1. Choose a webhook and click Actions > Update.
2. Change the status from Active to Inactive.
3. Click the Save button.

Deleting a webhook

To delete a webhook:

1. Choose a webhook and click Actions > Remove.
2. Click Yes to confirm.
3. The webhook is removed.

<p class="sm-help-tag">sm_help_admin_system_manage_webhooks</p>