Webhook

Why use webhook

Subscribe to webhooks

Receive webhook callbacks

⤷ Structure of POST body

⤷ Example POST body

⤷ Signature validation (security object)

Why use webhook 

EduMS provides webhooks that deliver updates regarding data changes, such as orders and their statuses. By subscribing to these webhooks, you can receive timely notifications about relevant changes.

Subscribe to webhooks

Subscribing to webhook events is simple:

  1. Identify the webhook you wish to subscribe to. These determine the specific resource for which you'll receive notifications and the corresponding operations (e.g., for order changes, select the webhook with resource "orders" and action "modified"). Use the GET webhooks endpoint to determine the appropriate webhook.

  2. Subscribe to webhooks by making a POST request to the webhook subscription endpoint. Include the required properties in the request payload.

Receive webhook callbacks

When a callback is triggered, the webhook API will send a POST request to the specified callback URL. 

Callbacks are executed once, regardless of the response, there is no retry policy.

All webhooks follow these guidelines:

  • POST an object with the same structure.

  • Include a security object as proof of sender (see below).

To ensure proper functionality, please adhere to the following:

  • HTTPS connection with a valid SSL certificate.

  • Return HTTP status code 200 OK within the 100-second timeout window.

Structure of POST body

{ 
  "webhookSubscriptionId": "<GUID>",
  "resource": "<resource name>",
  "action": "<Action of the resource, e.g. Created, Modified or Deleted>",
  "dateNotification": "<DateTime.UtcNow as a ISO8601 string>",
  "urlReference": "<direct URL to GET order-status-transition details>",
  "eventData": "<Optional JSON object of the affected data>",
  "modifiedFields": "<the list of fields in the eventData that where affected>",
  "webhookCallbackSecurity": {
    "nonce": "<randomly generated string>",
    "hash": "Base64Encoded(SHA256(dateNotification + action + urlReference + nonce + sharedSecret))"
  }
}

Example POST body

{ 
  "webhookSubscriptionId": "23bc0151-52e6-4ae6-8894-97a4ef4dbd71", 
  "resource": "educational-fulfillments", 
  "action": "Modified", 
  "dateNotification": "2020-05-12T19:32:46.3537589Z", 
  "urlReference": "https://api-edums-nl-dev.evi.cloud/fulfillment/v1/educational-fulfillments/f6ea2228-6a0c-4e18-8837-68c5c374ab24", 
  "eventData": { 
    "location": "Dijkerstraat-1", 
    "completed": true, 
    "startMomentId": null, 
    "startDate": null, 
    "dateCompleted": "2020-05-12T12:00:00.0000000Z", 
    "oleType": "None", 
    "dateDiplomaExpires": null, 
    "examStatus": null, 
    "permanentEducationPoints": 0.00, 
    "id": "f6ea2228-6a0c-4e18-8837-68c5c374ab24" 
    }", 
  "modifiedFields": [ 
    "completed", 
    "dateCompleted" 
    ], 
  "webhookCallbackSecurity": { 
    "nonce": "5f257f14-d00b-49d2-8c48-8671eec7bd56", 
    "hash": "fPF0062qJGd/fBrFwOtVWgdrhXUI/B81GqRJ4yhCmIo=" 
    }
}

Signature validation (security object)

To verify the authenticity of the callback message from EduMS, a webhookCallbackSecurity object is needed. 

This object includes: a nonce (a randomly generated value for each event callback), and a base64 encoded SHA256 hash of concatenated fields: 

This message is then used to create a SHA256 and that would be base64 encoded for the JSON body. The following CyberChef recipe shows how to generate the correct value: CyberChef recipe.

Example of the security object

Based on the data above, this is an example message:

2020-05-12T19:32:46.3537589ZModifiedhttps://api-edums-nl-dev.evi.cloud/fulfillment/v1/educational-fulfillments/f6ea2228-6a0c-4e18-8837-68c5c374ab245f257f14-d00b-49d2-8c48-8671eec7bd56Secret123

The SHA256 thereof is:

fPF0062qJGd/fBrFwOtVWgdrhXUI/B81GqRJ4yhCmIo=