About webhooks

Setting Up a Webhook

• Specify the Webhook URL: In your API request body, include the external_webhook_url key with the URL of your webhook receiver.
• Test with the webhook: For development and testing purposes, you can use webhook.site to simulate receiving webhook data.

API Request Example

Include the following key-value pair in your API request body:

"external_webhook_url": "www.exmaple.com/webhool_url"

Webhook Response Example

Upon completion of the call, the webhook URL will receive a response like the following:

{
    "status": "completed",
    "error_message": "agent_goodbye",
    "lead": {
        "name": "David",
        "phone_number": "+1234334546"
    },
    "call": {
        "status": "completed",
        "end_call_reason": "completed",          
        "model_id": "1711241656808x745681686585854500",
        "timezone": "Europe/Berlin",
        "call_id": "1711646262471x768387119913843100",
        "duration": 32,
        "start_time": "2024-03-28T18:17:46.205134+01:00",
        "transcript": "\nbot:  Hello, I am calling from Majestic Estates! I've seen you complete our form on the website about selling. Do you have a couple of minutes to finish the request? \nhuman:  Yes. I want to buy a car.\nbot:  Oh, that's exciting! But let's focus on your property for now. Are you planning to sell it or rent it out? \nhuman:  I want to buy a car by",
        "diversion": null,
        "external_id": "test_external_id"
    },
    "executed_actions": {
        "extract_info_1": {
            "name": "extract_info_1",
            "action_type": "extract_info_action_type",
            "description": "",
            "parameters_hard_coded": {
                "identifier": "purchase",
                "condition": "if user wants to purchase an item",
                "choices": null,
                "examples": [
                    "car",
                    "house"
                ]
            },
            "error_message": null,
            "return_value": {
                "purchase": "car"
            }
        }
    }
}

Understanding the Call Object States

The call object in the webhook response contains a status field which can have various values, each indicating a different state of the phone call. Below is a table explaining these statuses:

End Call Reason

This end_call_reason parameter provides insight into the reason why a call ended:

Webhook Security (Signature Validation)

Why Signature Validation is Critical

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. Signature validation ensures authenticity (the sender is Synthflow) and integrity (the payload hasn’t been altered).

How do I secure my webhooks?

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.

What is webhook signature validation for, and how critical is it?

Webhook signature validation verifies that the HTTP request originates from Synthflow. It prevents attackers who discover your webhook URL from sending forged payloads to your endpoint.

What are the risks if there is no secret key?

An attacker can send fake call payloads to your webhook, potentially compromising your data. For example, if your webhook is connected to a CRM, fake payloads could create fraudulent appointments with your customers.

How is signature validation used during a call?

For both inbound and outbound calls, Synthflow includes a signature in an HTTP header, and the call_id field is always part of the signed payload. The signature header is present on inbound webhooks and post-call webhooks.