About webhooks

Webhooks allow you to receive real-time notifications when a call is completed, eliminating the need to manually check for updates. By setting up a webhook, you can automatically capture call status, lead details, transcripts, and more, making it easy to integrate Synthflow AI with your existing workflows.

With webhooks, you can:

• Log call data in your CRM after an interaction.
• Trigger follow-up actions based on call outcomes.
• Monitor call performance in real-time.

To set up a webhook, provide a webhook URL in your API request. When the call is completed, Synthflow AI will send a structured response to your endpoint with details like call status, duration, and executed actions.

About 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:

1
import hmac  
2
import hashlib  
3
import base64  
4
5
def generate_hmac_signature(secret_key: str, payload: str) -> str:
6
    """
7
    Generates an HMAC-SHA256 signature.
8
9
    Args:
10
        secret_key (str): The private API key used to sign the payload.
11
        payload (str): The JSON payload (or message) being signed.
12
13
    Returns:
14
        str: The base64-encoded signature.
15
    """
16
    # Create an HMAC-SHA256 signature
17
    signature = hmac.new(secret_key.encode(), payload.encode(), hashlib.sha256).digest()
18
19
    # Return as a base64 string
20
    return base64.b64encode(signature).decode()
21
22
def verify_hmac_signature(  
23
    secret_key: str, payload: str, received_signature: str  
24
) -> bool:  
25
    """  
26
    Verifies an HMAC-SHA256 signature.
27
Args:
28
    secret_key (str): The private API key.
29
    payload (str): The original JSON payload (message).
30
    received_signature (str): The base64-encoded signature received.
31
32
Returns:
33
    bool: True if the signature is valid, False otherwise.
34
"""
35
    expected_signature = generate_hmac_signature(secret_key, payload)
36
37
    # Compare the received signature with the expected signature securely
38
    return hmac.compare_digest(expected_signature, received_signature)
39
40
call_id = "123456789"  
41
secret_key = "your-secret-key"  
42
signature = "abc123"  
43
is_signature_valid = verify_hmac_signature(secret_key, call_id, signature)  
44
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