Authenticated Callbacks

We use callbacks (also known as webhooks) to notify you about data changes in our system.
You have fine-grained control over which events trigger callbacks and which do not.

Authentication Options

📘

HTTPS is Mandatory

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

Callbacks can be sent with or without authentication.

We recommend using OAuth 2.0 (Client Credentials Flow) for secure delivery, but it is up to you to decide. We currently support:

• No authentication
• OAuth 2.0 authentication according to RFC 6749, Section 4.4.2

Regardless of your choice, we need to activate callbacks for your account. You'll need to let us know whether you want to receive callbacks, and if you prefer to use authentication.

Using OAuth 2.0 for Callbacks

If you choose OAuth 2.0 authentication, please provide the following:

• client_id
• client_secret
• token_uri (your OAuth 2.0 token endpoint)
• (Optional) scope — if your system uses scoped access

We will use this information to request an access_token before each callback.

Token Request Example

Below is an example of how we request a token using your provided credentials and token URI:

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'

The client_id and client_secret are included via Basic Auth and base64-encoded.
Ensure your endpoint accepts this format as per RFC 6749.

Please Note

• The Content-Type must be application/x-www-form-urlencoded.
• Parameter names must follow the OAuth 2.0 standard: grant_type, scope, etc.
• The client_id and client_secret are sent using HTTP Basic Auth, encoded as base64.

Your token server should return a standard OAuth response:

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

Important Notes on Encoding

📘

Encoding special characters in credentials

If your credentials include special characters (e.g. /, +), we first URL-encode the full string, then Base64-encode it.

For example:

• Credential: myClientId:abc/+123
• URL-encoded: myClientId:abc%2F%2B123
• Base64-encoded: bXlDbGllbnRJZDphYmMlMkYlMkIxMjM=

Your server must Base64-decode and then URL-decode the credentials to validate them. Most OAuth 2.0 libraries (e.g. Spring Boot) handle this automatically.