Introduction to EduBase Webhooks

Prerequisites

To use webhooks, you need the following:

• an EduBase account
• an organization with contents and members

Enable webhooks

To enable webhooks for your organization, you need to have the Webhooks feature enabled. If you do not see the option to manage webhooks, please contact us. Once enabled, webhooks can be managed from the dedicated page, accessible from the organization manager.

Webhooks can be configured to trigger on various events, such as when a new test result is available or previous results are updated. You can also set up multiple webhooks for the same events with different endpoints, or the same endpoint with different events. Webhooks can also be disabled temporarily if necessary.

Events

Check the webhook events reference for a complete list of available events and their payload structures. The type of event will be indicated in the EduBase-Webhook-Event header of the request.

Integrity

Payload verification

To ensure the integrity and authenticity of the webhook requests, signatures are sent along the request. This allows your application to verify that the request is genuine and has not been tampered with. The signature is generated the following way:

• Request parameters are sorted by key alphabetically
• They are then concatenated and URL query encoded (following the RFC 1738 standard) into a single string
• The resulting string is then hashed using the HMAC-SHA256 algorithm with the secret signature key generated for the organization (also accessible in the webhook configuration window)
• This signature is then included in the request headers as EduBase-Webhook-Signature-Payload

Sample code to generate the signature in PHP:

$payload = [
    'user' => '0000000000000000',
    'name' => 'Test User',
    'age'  => 42,
    'test' => true,
    'date' => '2020-01-01 12:12:12',
];
ksort($payload);
$serialized = http_build_query($payload, encoding_type:PHP_QUERY_RFC1738);
// $serialized = "age=42&date=2020-01-01+12%3A12%3A12&name=Test+User&test=1&user=0000000000000000"
$signature = hash_hmac('sha256', $serialized, 'SECRET_KEY');
// $signature = "2b48b3ae8ffec79fc73b43bf5859f8953e43cf537ef1c7fff33869c90b6ee781"

Headers verification

Similarly, to verify the special headers of the webhook request, a signature is generated using the same method as above, but instead of using the request parameters, the headers are used. Only headers starting with EduBase-Webhook- are included, except for EduBase-Webhook-Signature- headers. The resulting signature is sent in the request headers as EduBase-Webhook-Signature-Headers.

Debugging

You can manually trigger webhooks from the webhook management page. This is useful for testing and debugging purposes. Additionally, if a webhook fails to deliver its payload, the error details are logged and can be reviewed in the webhook debug popup, accessible from the same management interface (only if errors occur). Such manual test notifications are marked with the EduBase-Webhook-Test: true header! Furthermore, the base strings used to generate the signatures are also included in the headers as EduBase-Webhook-Signature-Payload-Base and EduBase-Webhook-Signature-Headers-Base for easier debugging.