Introduction

In simple terms, Webhooks, also known as web callbacks, are a straightforward method that enables an application or system to provide real-time information whenever an event occurs. Essentially, it is a way to passively receive data between two systems through HTTP POST requests.

When the webhook is activated, any changes to integrated resources will trigger a POST request to the configured endpoint, containing information about the event and the involved resource.

Client Authentication Information (Setup the webhooks)

To ensure that we are sending the webhook to the right place, we implement at least one method of authentication with the destination URL. The authentication methods are described below.

• API Key
• Basic Auth
• Bearer Auth
• JWS

API Key

In the API Key model, the client needs to provide us with the API authentication key to be used in the webhook call, as well as the name of the header to be used.

Example:

Basic Auth

In the Basic Auth model, the client needs to provide us with the client_id and client_secret to be used in the authentication of the webhook API call, as well as the name of the header to be used.

Example:

Bearer Auth

In the Bearer Auth model, the client needs to provide us with a curl or similar with the necessary data to call the token generation route and obtain a JWT or opaque token to be used in the authentication of the webhook API call, as well as the name of the header to be used.

Example of authentication route:

curl -X POST \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=client_credentials" \\
  -d "client_id=your_client_id" \\
  -d "client_secret=your_client_secret" \\
  <https://your-api.com/oauth/token>

Example of webhook call:

JWS

In the JWS model, we provide the public signing certificate used. If this form of authentication is chosen, we will convert the webhook payload into a JWT signed with a signing certificate using a private key and share the public key for the client to verify the payload signature, confirming that it was sent by us.

Security Methods

To secure the webhook payload, we employ at least one of the methods below.

• Mutual TLS
• JWE

Mutual TLS

In the Mutual TLS method, when sending the webhook during the handshake, we verify if the client's certificate was issued from an issuer provided by the client. Upon verifying the authenticity of the server certificate, we send the request with our certificate, and the server, in turn, can verify if our certificate was issued from a previously provided issuer.

JWE

In the JWE method, similar to the JWS method, we convert the webhook payload into an encrypted JWT with a public encryption certificate provided by the client and send the request to the client, who decrypts it with the private key.