Webhook Security

HMAC Signature Authentication

This document explains how to use HMAC (Hash-based Message Authentication Code) signatures to secure webhook communications.

Overview

The HMAC signature system provides a way to verify the authenticity and integrity of webhook payloads. It uses a shared secret key to generate and verify signatures, ensuring that messages haven't been tampered with during transmission.

Getting Started

1. Generate a Secret Key

First, you need to go to Synthflow UI and generate your secret. The secret is valid for a single workspace.

Each user and workspace will have a different secret key.

Navigate: Go to Integrations tab > Webhook Security tab > Click on button Generate Secret Key

2. External webhook signature

We will use the call id as the payload and the secret key to generate the signature. We will send the signature in the header of the request when calling the user set webhook

HTTP_SYNTHFLOW_SIGNATURE: abc123

3. Verify the signature

The user can verify the signature using the secret key and the call id. Here is a sample code in python:

import hmac  
import hashlib  
import base64  
import secrets

def verify_hmac_signature(  
    secret_key: str, payload: str, received_signature: str  
) -> bool:  
    """  
    Verifies an HMAC-SHA256 signature.
Args:
    secret_key (str): The private API key.
    payload (str): The original JSON payload (message).
    received_signature (str): The base64-encoded signature received.

Returns:
    bool: True if the signature is valid, False otherwise.
"""
expected_signature = generate_hmac_signature(secret_key, payload)

# Compare the received signature with the expected signature securely
return hmac.compare_digest(expected_signature, received_signature)

call_id = "123456789"  
secret_key = "your-secret-key"  
signature = "abc123"  
is_signature_valid = verify_hmac_signature(secret_key, call_id, signature)  
print(is_signature_valid)

If the output of the function is true, then the signature is valid and comes from Synthflow.

Security Details

• Uses HMAC-SHA256 for signature generation
• Secret keys are 256-bit (32 bytes) cryptographically secure random values
• Signatures are base64-encoded for safe transmission
• Uses constant-time comparison to prevent timing attacks