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

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

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

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  

def generate_hmac_signature(secret_key: str, payload: str) -> str:
    """
    Generates an HMAC-SHA256 signature.

    Args:
        secret_key (str): The private API key used to sign the payload.
        payload (str): The JSON payload (or message) being signed.

    Returns:
        str: The base64-encoded signature.
    """
    # Create an HMAC-SHA256 signature
    signature = hmac.new(secret_key.encode(), payload.encode(), hashlib.sha256).digest()

    # Return as a base64 string
    return base64.b64encode(signature).decode()

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