Webhooks Security

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.

Signature validation ensures authenticity (the sender is Synthflow) and integrity (the payload hasn’t been modified).

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 enable and verify webhook signatures

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 the inbound webhook and the post-call webhook.

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