Webhooks

Webhooks are a powerful tool for developers to receive real-time notifications when specific events occur. By setting up webhooks, you can be instantly informed when people's or group's properties change, allowing your application to respond immediately to these updates. This can enhance the user experience by ensuring that your system remains synchronized with the latest user data.

IDM Webhooks on Eduplaces

When configuring webhooks on Eduplaces, you specify a URL and subscribe to event type. When one of these events occurs and is relevant for your application, Eduplaces sends an HTTP POST request to the URL you provided.

Event Types

Eduplaces supports the following event types:

You can decide which event types you want to subscribe to when setting up a webhook. Thes event type will be included in the payload of the HTTP POST request as well as the HTTP header X-EP-Event-Type to ease parsing the payload.

Person vs. People vs. User

We distinguish between people and user to represent synchronized individuals and users with access to the application respectively. We use person to refer to the group of entities that can be either of these or both. A person can be present in both people and user sets. However, we only send a webhook once for that person.

Payload

Common Properties

All webhook payloads contain the following properties:

• event: The event type that triggered the webhook.
• action: The action regarding that event type. Can be one of the following: create,update,delete,restore
• updatedProperties (optional): A list of properties that have been updated.

Event Type person

The payload for the person event type contains the following properties:

• personId: The ID of the person.
• updatedProperties: List of properties that have been updated. (name, role, status, groups)

Event Type group

The payload for the group event type contains the following properties:

• groupId: The ID of the group.
• updatedProperties: List of properties that have been updated. (name, status)

Event Type school

The payload for the school event type contains the following properties:

• schoolId: The ID of the school.
• updatedProperties: List of properties that have been updated. (name, address, schooling_level, official_id)

Signature Verification

To ensure that the webhook payload was sent by Eduplaces and not by a malicious third party, you can verify the signature of the payload.

Eduplaces includes a signature in the X-EP-Signature-Sha256 header. It is a SHA-256 HMAC of the HTTP body using the webhook secret you received when creating the webhook.

printf HTTP-Body-Payload | openssl sha256 -hmac "webhook-secret"
# output: SHA2-256(stdin)= 2ceabcc78a1527246639b070039e8ba84bbac97c7c55fe0a5163b7b755aa02ed

import { createHmac } from 'node:crypto';

function sign(payload: string, secret: string): string {
  const hmac = createHmac('sha256', secret);

  hmac.update(payload);

  return hmac.digest('hex');
}

echo hash_hmac('sha256', 'payload', 'secret');

Handling Webhook Deliveries

When handling a webhook delivery, you should parse the request body according to its event type. That type is included in the X-EP-Event-Type header. Then, you should handle the event based on your application's requirements. You might want to use the IDM API to fetch the latest data for the user, group, or school that triggered the webhook. You may choose to ignore the event if it is not relevant to your application (e.g. a user's group membership was updated, but your application does not display user's groups).

When Eduplaces sends a webhook, your server should respond with a 2xx HTTP status code to indicate that the webhook was received successfully. If your server responds with any other status code, Eduplaces will consider the webhook delivery as failed and will retry sending the webhook up to 3 times.

During development, you can use tools like ngrok or smee to expose your local server to the internet and test your webhook handling.

Examples

The following example use the webhook secret e6GKOQDuPPubIF7YwzXmp0Z24Y+rcOscdf/86vZNQMM= for signature verification.

POST /webhook HTTP/1.1
Host: eduplaces-app.local
Content-Length: 111
X-EP-Signature-Sha256: 16048aa83e4d9a44c854b8510546f8d91ba0af9f24f5761fb2c66fe716999a54
X-EP-Event-Type: person
User-Agent: Eduplaces/1.0
Content-Type: application/json
Accept: application/json, text/plain, */* 

{"event":"person","action":"update","personId":"10adffa1-5ccd-481c-afc0-b5b8728d140d","updatedProperties":["role"]}

POST /webhook HTTP/1.1
Host: eduplaces-app.local
Content-Length: 113
X-EP-Signature-Sha256: 0a9a0d1bf08351e86dfe749ebe67da1d0fc1251133815b45ad6337e4aca3e3dd
X-EP-Event-Type: group
User-Agent: Eduplaces/1.0
Content-Type: application/json
Accept: application/json, text/plain, */* 

{"event":"group","action":"update","groupId":"21bc2a54-db7b-40f4-9842-ef7eba9d857b","updatedProperties":["name"]}

POST /webhook HTTP/1.1
Host: eduplaces-app.local
Content-Length: 162
X-EP-Signature-Sha256: aa750064f72bf5443c74888e856b10d1956d19de9684bc54026f6883e6192ee7
X-EP-Event-Type: school
User-Agent: Eduplaces/1.0
Content-Type: application/json
Accept: application/json, text/plain, */* 

{"event":"school","action":"update","schoolId":"f2b4533a-9a57-4368-85e5-3dc90bd2b434","updatedProperties":["address"]}