HMAC Authentication for Incoming Webhooks

This article explains how HMAC authentication works on the incoming webhook step, when to use it, and what to expect once it is enabled.

For how to add an incoming webhook step to your workflow, see Setting Up an Incoming Webhook Step in Streamline.

For implementation details and code examples, see Intellistack Developer Portal.

What HMAC Does

HMAC (Hash-based Message Authentication Code) is an authentication option on the incoming webhook step. It protects your webhook in two ways:

• Proves who sent the request - Only a system that possesses your shared secret key can produce a valid signature. Even if someone discovers your webhook URL, they cannot trigger the workflow without the key.
• Proves the data was not changed - The signature is computed from the exact request body. If any part of the payload is modified after signing - even a single character - the signature will not match and the request is rejected.

These two protections work together. A valid request requires both the correct secret and an unmodified payload.

When to Use HMAC

Protecting Sensitive Data

If your webhook payload includes personally identifiable information (PII), financial data, medical records, or other sensitive information, HMAC ensures that only your authorized system can send that data into the workflow and that nothing was altered in transit.

Restricting Who Can Start Sessions

Without HMAC, anyone with the webhook URL can trigger your workflow. With HMAC enabled, only systems that possess the secret key can create sessions. This is important when workflows should only be initiated by specific applications or services.

Embedding Behind an Authenticated Portal

If you embed a Streamline workflow in a customer portal, employee intranet, or partner site, HMAC lets your portal pass logged-in user information (name, email, account details) into the workflow securely. Your portal's backend signs the payload with the HMAC secret, and Streamline creates a session with that data prefilled.

For embedding setup, see Embedding Workflows on Your Website.

Server-to-Server Integrations

If you trigger workflows from a CRM, ERP, or backend service, HMAC verifies that requests are coming from your authorized system and have not been intercepted or modified by a third party.

What Happens When HMAC Is Enabled

When you enable HMAC authentication on an incoming webhook step:

• Direct link is disabled - Users cannot start sessions by visiting the workflow URL directly
• QR code is disabled - The QR code for the workflow is no longer functional
• All requests require a valid signature - Requests without the Streamline-Signature header or with an invalid signature are rejected with a 401 Authentication failed error
• Test mode validates signatures - When using the test URL (?test=true), HMAC authentication is still enforced, so you can verify your setup before going live

Sessions can only be created through the HMAC-authenticated webhook endpoint.

How to Enable HMAC Authentication

Step 1: Create a Webhook Connection

Before you can use an incoming webhook in a workflow, you need to create a webhook connection on the Integrations page.

1. Navigate to the Integrations page
2. Click + New connection in the upper right
3. Select Webhook from the integration catalog
4. In the Connect to Webhook dialog:
   • Enter a Connection name (for example, "Incoming webhook" or a name that identifies the use case)
   • Select Incoming
   • Click Create
5. Streamline generates an HMAC secret key. Copy this key and store it securely - your development team will need it to sign requests
6. Click Done

The connection now appears on your Integrations page with a Connected status. To view the HMAC secret key again later, click Edit details on the connection.

Step 2: Add an Incoming Webhook Step to Your Workflow

If your workflow does not already have an incoming webhook step, add one as the first step of your workflow and associate it with the webhook connection you created in Step 1.

For detailed instructions on configuring the webhook step, including field mapping and test payloads, see Setting Up an Incoming Webhook Step in Streamline.

Step 3: Publish Your Workflow

Publish the workflow to apply the changes. Until the workflow is published, the HMAC authentication setting does not take effect.

Step 4: Hand Off to Your Development Team

Provide your development team with:

• The HMAC secret key from Step 1
• The Incoming Webhook URL from the webhook step configuration

Your development team will use these to implement the server-side signing logic. HMAC signing must be performed on your backend - never include the secret in client-side code.

For implementation details and code examples in JavaScript, Python, Java, and cURL, see Embedding with HMAC Authentication on the Intellistack Developer Portal.

What You Need to Get Started

HMAC requires your development team to implement the signing logic in your application. This is not a no-code setup.

Troubleshooting