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.

Webhook security

Overview

Synthflow signs every webhook payload with an HMAC using your shared secret key. The resulting signature, included in the HTTP_SYNTHFLOW_SIGNATURE header, lets you confirm that the payload came from Synthflow and was not altered in transit.

Why signature validation matters

While TLS (HTTPS) protects against eavesdropping and tampering during transit, it does not guarantee that the request is genuinely coming from Synthflow. Without signature validation, an attacker who discovers or guesses your webhook URL can send forged payloads. These spoofed calls could trigger workflows, write bad data, or corrupt your system. Without a secret key, for example, a malicious actor could create fraudulent appointments in your CRM by replaying fake call payloads.

How to secure your webhooks

1. Go to Settings > Security > Webhooks and generate a secret key. Synthflow uses this key to generate a signature that is included in the webhook HTTP header for every call.

2. Send the signature header with every webhook. Synthflow uses the call_id as the payload and signs it with your secret key before adding it to the HTTP_SYNTHFLOW_SIGNATURE header.

   ht

   HTTP_SYNTHFLOW_SIGNATURE: abc123

   Synthflow includes this header on both inbound webhooks and post-call webhooks.

3. Verify the signature on your side using the same secret key and the received call_id.

   1
   import hmac
   2
   import hashlib
   3
   import base64
   4
   5
   def generate_hmac_signature(secret_key: str, payload: str) -> str:
   6
       signature = hmac.new(secret_key.encode(), payload.encode(), hashlib.sha256).digest()
   7
       return base64.b64encode(signature).decode()
   8
   9
   def verify_hmac_signature(secret_key: str, payload: str, received_signature: str) -> bool:
   10
       expected_signature = generate_hmac_signature(secret_key, payload)
   11
       return hmac.compare_digest(expected_signature, received_signature)
   12
   13
   call_id = "123456789"
   14
   secret_key = "your-secret-key"
   15
   signature = "abc123"
   16
   is_signature_valid = verify_hmac_signature(secret_key, call_id, signature)
   17
   print(is_signature_valid)

   If the output is True, the payload originated from Synthflow and was not altered in transit.

Technical 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