Webhooks

Webhooks allow you to subscribe to events triggered on a Falkor Pathway. When an event is triggered to the webhook's configured URL, an HTTP POST payload is sent along with an HMAC sha256 signature.

Webhook Setup

Step 1 When a pathway is created, webhooks are automatically registered in a disabled state. To set up a webhook, go to the API & Webhooks section of the pathway. From there, select the MPI Manager options icon and choose Setup.

Step 2 Provide a secure URL and Webhook Secret. A secrets is used to create a signature of the payload data and is sent in the <Platform Name>-Webhook-Signature header. This ensures that you can validate that the payload is in fact from the platform. We do recommend you provide a strong cryptographic token.

<Platform Name> will be the name of the platform being used. For example: ByteKast-Webhook-Signature, TrainiApp-Webhook-Signature OR Falkor-Webhook-Signature

Step 3 Once your chosen webhook is set up, you can enable it by clicking the switch to on. Once enabled, you can begin to manually send deliveries to test integrations on your server.

Validating Payloads

During a webhook setup, your provided secret is used to sign the payload with an HMAC SHA256 signature. This signature is available in the payload header as Falkor-Webhook-Signature

To validate this signature you will use the same secret to along with the sent payload to recreate the matching signature. For example, in PHP this would simply be:

/**
* Consume the header and signature sent by Falkor. The signature
* will be generated using HMAC SHA256 with the provided shared
* secret.
*/

$payloadSignature = explode('sha256=',$_SERVER['HTTP_FALKOR_WEBHOOK_SIGNATURE']);
$payloadData      = file_get_contents('php://input');


/**
* Rebuild the matching signature using the same shared secret
* and the payload sent by Falkor.
*/

$yourSecretToken = 'ff820d62b80b7c2789286f691b5e89bd';

// Rebuild Matching Signature
$matchSignature  = hash_hmac('sha256', $payloadData, $yourSecretToken);


/**
* Check the sent signature matches the rebuilt signature.
*/

if ($payloadSignature[1] == $matchSignature):
   // Signature Matched
else:
   // Did Not Match
endif;

Available Webhook Events

Enrolments

Triggered when enrolments for a pathway change. This can be when a user enrols, or completes a pathway or activity.

Enrolments

Classroom & Event Bookings

Triggered when attendance for a classroom or event changes. This is when the user registers their attendance or checks-in to the activity.

Classroom & Events

Rewards

Triggered when rewards are obtained by users, i.e. is when the user receives/unlocks the reward on a pathway.

Rewards