Menu

Webhook Headers & Authentication

 When sending data from Flarie to external systems, it is important to secure your webhook requests. Flarie provides flexible authentication options and full control over request headers to help protect your integrations. 

Request Authentication Configuration

You can choose how your webhook requests are authenticated.

1. None

No authentication is included in the request. Use this only for public endpoints or testing.

 

2. Flarie Authentication (recommended)

Automatically includes your API Access Key as a Bearer token.Authorization: Bearer <accessKey>This ensures requests can be verified as coming from Flarie.

Recommendation:  Validate this token on your server to confirm the request source.

 

3. Custom Authentication

Use this when your endpoint requires specific credentials.

Basic AuthEnter a username and password. These are encoded and sent as: Authorization: Basic <base64(username:password)>

Bearer TokenEnter a token that will be sent as:Authorization: Bearer <your_token>

 

4. OAuth 2.0

Use OAuth 2.0 when your receiving endpoint requires an access token from an authorization server.

Flarie supports the Client Credentials grant, automatically requesting and managing access tokens so you don't need to update them manually when they expire.

Configuration 

Select OAuth 2.0 under Authentication Type and configure the following fields:

  • Token URL (Required) – The HTTPS endpoint where Flarie requests an access token from your authorization server.
  • Client ID (Required) – The client identifier provided by your authorization server.
  • Client Secret (Required) – The secret associated with your Client ID.
  • Scope (Optional) – Defines the permissions requested for the access token.
  • Audience (Optional) – Identifies the API or resource the token is intended for, if required by your authorization server.
  • Client Authentication – Choose how your credentials are sent when requesting a token:
    • Send as Basic Auth header (default) – Sends the Client ID and Client Secret in the Authorization header.
    • Send in request body – Includes the Client ID and Client Secret in the token request body.
  • Token Prefix – The prefix added before the access token in the webhook's Authorization header. Defaults to Bearer.

How it works

When a webhook is triggered, Flarie automatically obtains an access token from your authorization server and includes it in the webhook request:

Authorization: Bearer <access_token>

Flarie securely stores and reuses valid access tokens, automatically requesting a new token when needed.

If a previously obtained token is rejected with a 401 Unauthorized response, Flarie attempts to obtain a new token and retries the webhook once.

If authentication fails, the webhook follows the standard failure and resend handling, provided retries are enabled.

Important to know

  • Only the OAuth 2.0 Client Credentials grant is supported.
  • The Token URL must use HTTPS.
  • Your Client Secret is encrypted and hidden when editing an existing configuration.
  • If you change the Token URL, you must enter the Client Secret again.
  • You can use Test Webhook to verify your authentication configuration before activating the integration.

 

 

Custom headers

You can add additional headers to your webhook request.

  1. Click Add Header +.
  2. Enter a header name and value.

Example:Header name: x-api-keyHeader value: 12345-ABCDEThis will be sent with the request and can be used for authentication or metadata.You can combine custom headers with any authentication method.

 

X-Signature header (optional)

Learn how to enable Secret Key in Flarie Studio hereFor additional security, you can enable the X-Signature header.When enabled, each request includes a signature:

X-Signature: <HMAC-SHA256 signature>

This signature is generated using HMAC-SHA256 with your Secret Key and the request payload.

It allows you to verify that:

  • The request is from Flarie
  • The payload has not been modified

Verify signature (example)

const crypto = require("node:crypto");

// Example payload (exact JSON string from the request body)
const payload = // your json payload from the webhook
const payloadString = JSON.stringify(payload);

// Your Secret Key from Flarie Studio
const secretKey = "your-secret-key";

// Generate the expected HMAC-SHA256 signature
const calculatedSignature = crypto
  .createHmac("sha256", secretKey)
  .update(payloadString)
  .digest("hex");

// Compare with the X-Signature from the request header
const xSignature = "X-Signature-in-the-header";

if (xSignature === calculatedSignature) {
  console.log("✅ Payload is authentic and unmodified")
} else {
  console.log("⚠️ Payload is modified")
}

Recommendation

Using authentication together with X-Signature verification provides the highest level of security for your webhook integrations.

Need additional help setting up your integration? Contact Us