Real-time / Webhooks

The authorization type is selected when you register a webhook. All webhooks require authorization. There are two types of authorization methods:

Basic

When the authorization method is Basic, then a Webhook is expected to use a username and password for authorization as per RFC 7617 Basic Authentication.

 OAuth / Client Credentials

When the authorization method is Client Credentials, the client supports the OAuth2 Authentication Client Credentials Grant. A Webhook using Client Credentials must to have the following properties provided by the partner:

• A clientId, submitted as a one-line string. Do not include line breaks.

• A clientSecret, submitted as a one-line string. Do not include line breaks.

• A tokenUrl is the URL ,hosted by the partner (not hosted by Apiture) where the partner’ webhoot supports obtaining the Client Credentials access token. The URL must use the https:// protocol.

• The scope is the space-delimited scope values Apiture needs to Authenticate with the partner’s application. These scopes are defined by the partner, and are not the scopes associated with Apiture APIs.

As per the OAuth2 Authentication Client Credentials Grant flow The Apiture platform sends an HTTP POST to the webhook’s Token URL, passing the the grant_type of client_credentials and the Client ID, Client Secret, and scope, associated with the webhook’s authorization. This token URL identifies the webhook authorization that implements the OAUth2 token_endpoint.

The webhook token URL must return the standard OAuth2 token_endpoint; the response must include the "access_token" string and the "token_type" string; the token type is typically the string "Bearer". An example response from a POST to the webhook’s token URL is below:

{ "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600
}

Sending Authorization to the webhook

When the platform sends an event message to the webhook, it includes an Authorization: header. For the Client Credentials flow, this header value
consists of the corresponding token_type and access_token returned from the token URL, such as

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

for the example above.

If the webhook’s authorization is Basic Auth, the platform sends the standard Basic authorization header, with the encoded username/password associated with the webhook’s registration. For example, if the
webhook’s registration has the username of webhook-user and password insecure-password, the platform will send the following authorization header with each event message sent to the webhook:

Authorization: Basic d2ViaG9vay11c2VyOmluc2VjdXJlLXBhc3N3b3Jk

The partner’s webhook application must validate the required Authorization header and reject invalid or expired access_token values to ensure secure communication.