Authenticated Callback Usage

We use callbacks (also known as webhooks) to inform you about data changes in our system. We have implemented a lot of different callbacks for that purpose. You can very granularly control for which events you want to receive a notification via callback and for which not.

Callbacks can be send with or without authentication on your side. We advise for using oAuth2 here as a form of authentication. But it is up to you to decide whether you want to receive callbacks with or without authentication. We currently support:

• No authentication
• oAuth2 client credentials authentication according to RFC 6749

In both ways, we need to activate callbacks for you. So please let us know if you want to use callbacks and if you want to use them with or without oAuth2. If you prefer the oAuth2 authentication, please provide:

• oAuth2 Client-ID
• oAuth2 Client-Secret
• oAuth2 Token URI
• Optionally oAuth2 Scope, if you use this feature

The request we make to obtain the access token (Bearer token) from your oAuth2 server follows the mentioned RFC standard and looks similar to this:

curl 'https://my-auth-server.com/oAuth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic bXlDbGllbnRJZDpteUNsaWVudFNlY3JldA==' \
--data-urlencode 'grant_type=client_credentials'
--data-urlencode 'scope=PLIANT'

Please note the

• correct Content-Type,
• the parameter naming and
• that clientId and clientSecret are passed via Basic Auth to your oAuth server. In this example we send: myClientId:myClientSecret (url-)encoded as base64.

📘

Important

If your credentials contain any special characters in the sense of a URL, like a / or a +, we will first url-encode the string, then base64-encode it. Meaning a credential pair like myClientId:abc/+123 will be send as Basic bXlDbGllbnRJZDphYmMlMkYlMkIxMjM= which is base64-decoded then myClientId:abc%2F%2B123. Meaning your implementation needs to be aware of this and utilize url-decoding and base64-decoding to check the validity of the Basic Auth. Standard oAuth2 implementations and libraries do that already under the hood, like Spring Boot for instance.

The expected response for this request is:

{
    "access_token": "...",
    "expires_in": ...
    "token_type": "Bearer"
  	...
}

📘

HTTPS is Mandatory

All API communication must be made over HTTPS, plain HTTP is not allowed.