Authentication and security

To prevent interception of PII and access token hijacking, all traffic to the webhook endpoint has to be over TLS. The endpoint uses OAuth 2.0 authentication (Client Credentials grant), to prevent other parties calling the endpoint with fake events, which could act as a denial-of-service attack. For the purpose of using OAuth, the integrating party has a choice:

1. Use your own identity provider (managed by the implementer or a service) in which case the client_id, client_secret and token URL should be sent to Textkernel.
2. Reuse Texternel's authentication provider (which is also used by Textkernel's Data Enrichment APIs).

OAuth 2.0

OAuth provides security controls for the Events Webhook. OAuth is an open authorization protocol used to share resources with applications. OAuth enables scoped access to your resources, so that the username and password don’t have to be shared with the application.

The Automation API uses the Client Credentials OAuth grant type, which is an authorization workflow for machine-to-machine communication. This authorization method creates a token that the Automation API can pass to your app in an Authorization header, allowing you to verify that the request originated from Automation API.

OAuth Client Credentials flow

Below is a description of the setup flow:

1. You, the client or integrating party, have an app that consumes an HTTP webhook. You want the Automation API Events Webhook to make POST requests to this URL. To ensure that the webhook requests you receive are actually from Automation API, you implement OAuth.
2. This means that you are responsible for generating a Client ID and Client Secret. You must also provide two URLs:
   1. the HTTP POST URL for your app
   2. a token URL that your authorization server exposes
3. You give the Textkernel Professional Services team all of this information, and we configure our infrastructure so that the Automation API passes the Client ID and Client Secret to the Token URL (your authorization server/OAuth service). Your authorization server will then use the Client ID and Client Secret to generate an access token. This token is then sent back to Textkernel's Automation API.
4. The access token acts as the identifier Textkernel uses when sending events to your HTTP POST URL. The token is communicated via an Authorization header.
5. The access token is only shared amongst your app, the authorization server, and Textkernel's Automation API, so you can trust that requests using the token are from a trusted source.
6. You can verify the access token is legitimate by checking it with the authorization server that created it.

Manage OAuth 2.0 using the API

You enable your webhook authentication by notifying the Textkernel Professional Services team about your credentials and URL details.