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
andclientSecret
are passed viaBasic Auth
to your oAuth server. In this example we send:myClientId:myClientSecret
(url-)encoded asbase64
.
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 likemyClientId:abc/+123
will be send asBasic bXlDbGllbnRJZDphYmMlMkYlMkIxMjM=
which is base64-decoded thenmyClientId:abc%2F%2B123
. Meaning your implementation needs to be aware of this and utilize url-decoding and base64-decoding to check the validity of theBasic 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.
Updated 8 months ago