Technical Details

Contents

Method of Communication

When a webhook is called, it sends a POST request including a few headers and a JSON-formatted body to the endpoint URL defined by the webhook subscription. The event name is added to the base URL. For example, if your base URL is https://example.com/webhooks and the event is startSession, the full URL that is called will be https://example.com/webhooks/startSession. Learn more about subscriptions here.

It then expects a response with a few headers and also a JSON formatted body. The HTTP response code should be 200 if the request was processed successfully and 400 when an error occurs. Learn more about the possible error codes here.

It is also possible that the response contains an error. MplusKASSA will then send a new request to the same endpoint URL, including the error that was detected and the original event details.

Communication Flow

Here is a schematic representation of the communication flow for a normal request and successful response.

MplusKASSA Webhook URL
(1) Event occurs Send request (2) Process request
(4) Process response Send response (3) No problems found
(5) No problems found

Here is a schematic representation of the communication flow for a normal request, but error response.

MplusKASSA Webhook URL
(1) Event occurs Send request (2) Process request
(4) Process error response Send error response (3) Problem found

Here is a schematic representation of the communication flow for a normal request and a successful response, but with an error found in the response.

MplusKASSA Webhook URL
(1) Event occurs Send request (2) Process request
(4) Process response Send response (3) No problems found
(5) Problem found Send error request (6) Process error request
(7) Maybe log error

Examples of Request and Response

Let’s explain further by showing some examples.

Example of normal request
Take note of the URL, the required request headers and the JSON body. The exact contents of the payload are not important, they are explained in other places.

Example of successful response:
Take note of the HTTP response code, the required response headers and the JSON body. The exact contents are not important, they are explained in other places.

Example of error response:
Take note of the HTTP response code, the required response headers and the JSON body. The exact contents are not important, they are explained in other places.

Example of error request
Take note of the URL, it’s the same as the original request. Also take note of the additional error element and the original element containing the original event.

Security measures

All communication over SSL
To prevent snooping, all webhook endpoint urls must communicate over SSL. In simple terms, any URL that is not preceded by https:// will not be supported.

Sign with HMAC
To provide a means of verification and protection against outside manipulation, a hash-based message authentication code (HMAC) is used. Hash your payload with the HMAC-SHA256 algorithm and encode the result in Base64.

To test if your implementation works, generate a hash based on the message test and the secret key (in Base64) eFc5HrxwLbONJ+EYXrbHB+a9HueYIQzotgKRLRVAfx0=. The result (in Base64) should be EBFFIb5qPH/teEFmjtwcIj6h80cl+X1DUy62D46tnu8=.

Please note that the secret key displayed here is just an example, in a production environment an unique key will be configurable (or automatically generated) for your application.

Secret Token Configuration

Another example

Secret: EBFFIb5qPH/teEFmjtwcIj6h80cl+X1DUy62D46tnu8=
Hash: 7H0jJ1U0Quc+m4GBo9oAhWVOuXS5pKlkjGhxnUxu+0c=

If you have a Webhook Test Suite account, you can use this page to generate more examples: https://webhooks.mpluskassa.nl/hmac