HMAC Authentication for Incoming Webhooks – Streamline

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.

What You Need to Get Started

What	Who provides it	Where it goes
HMAC secret key (whsec_...)	Generated in the incoming webhook step settings	Your application's server-side environment variables or secrets manager
Incoming webhook URL	Provided in the incoming webhook step settings	Your application's backend code
Signing implementation	Your development team builds this	Your application's server (never in browser or client-side code)

HMAC requires your development team to implement the signing logic in your application. This is not a no-code setup. For implementation guidance and code examples in multiple languages, see Intellistack Developer Portal.

Troubleshooting

Issue	What to check
401 Authentication failed	Verify the secret key matches, the Streamline-Signature header is present, and the signed payload is identical to the sent payload. Common causes: signing pretty-printed JSON but sending minified, or encoding mismatches with non-ASCII characters.
400 Bad Request	The Streamline-Signature header format is incorrect. It must be exactly sha256={hex} with no extra spaces or characters.
500 or 502 errors on a correctly signed request	This is a platform-side issue, not a problem with your request. Do not modify your signature or payload. Retry after a brief delay and contact support if it persists.
Prefilled data not appearing	Confirm the field names in your payload match the fields mapped in the incoming webhook step. Send a test payload to the test URL to verify field detection.
Direct link or QR code still works	Ensure HMAC authentication is fully enabled and the workflow is republished.