Webhooks in Flyflow

Webhooks are a powerful feature in Flyflow that allow you to receive real-time notifications and data about events occurring during a call. By configuring a webhook URL for your agent, Flyflow will send HTTP POST requests to that URL whenever specific events happen, enabling you to build custom integrations and perform actions based on the call data.

How Webhooks Work

When you create or update an agent in Flyflow, you have the option to provide a webhook URL. This URL should point to an endpoint in your application that is capable of receiving and processing HTTP POST requests.

During a call, whenever a relevant event occurs, Flyflow will send an HTTP POST request to the specified webhook URL. The request will contain a JSON payload with information about the event, including the event type and associated data.

Your application should be designed to handle these incoming webhook requests, parse the JSON payload, and perform any necessary actions based on the event type and data.

Supported Webhook Events

Flyflow triggers webhooks for the following events during a call:

1. call_started: This event is fired when a call begins. It indicates that a new call has been initiated and is being processed by Flyflow.

2. call_ended: This event is fired when a call ends. It signifies that the call has been completed, either due to the conversation reaching its natural conclusion or due to an interruption or disconnection.

3. tool_call: This event is fired when a tool is invoked during a call. Tools are predefined actions or integrations that can be triggered by the agent based on the conversation context. When a tool is called, Flyflow sends a webhook notification with details about the tool and any associated data.

Webhook Payload Format

The webhook payload sent by Flyflow follows a consistent JSON format. Here's an example of a webhook payload for a tool_call event:

{
  "event_type": "tool_call",
  "call_id": "abc123",
  "timestamp": "2023-06-08T10:30:00Z",
  "data": {
    "tool_name": "example_tool",
    "tool_input": {
      "param1": "value1",
      "param2": "value2"
    },
    "tool_output": {
      "result": "tool execution successful"
    }
  }
}

The payload includes the following fields:

• event_type: The type of the event that triggered the webhook (call_started, call_ended, or tool_call).
• call_id: The unique identifier of the call associated with the event.
• timestamp: The timestamp indicating when the event occurred.
• data: An object containing event-specific data.
  • For tool_call events, the data object includes:
    • tool_name: The name of the tool that was invoked.
    • tool_input: An object representing the input parameters passed to the tool.
    • tool_output: An object representing the output or result of the tool execution.

Handling Webhook Requests

To handle webhook requests in your application, you need to implement an endpoint that can receive HTTP POST requests. This endpoint should be able to:

1. Receive the incoming HTTP POST request from Flyflow.
2. Parse the JSON payload from the request body.
3. Extract the relevant information from the payload, such as the event type and associated data.
4. Perform any necessary actions or integrations based on the event type and data.
5. Respond with a valid HTTP response to acknowledge the receipt of the webhook.

It's important to ensure that your webhook endpoint is reliable, secure, and can handle the expected volume of requests from Flyflow.

Example Webhook Implementation

Here's a simple example of how you can implement a webhook endpoint in Python using the Flask web framework:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.get_json()
    event_type = payload['event_type']
    call_id = payload['call_id']
    timestamp = payload['timestamp']
    data = payload['data']

    # Process the event based on the event_type
    if event_type == 'call_started':
        # Handle call started event
        print(f"Call started: {call_id}")
    elif event_type == 'call_ended':
        # Handle call ended event
        print(f"Call ended: {call_id}")
    elif event_type == 'tool_call':
        # Handle tool call event
        tool_name = data['tool_name']
        tool_input = data['tool_input']
        tool_output = data['tool_output']
        print(f"Tool called: {tool_name}")
        print(f"Tool input: {tool_input}")
        print(f"Tool output: {tool_output}")

    # Respond with a success status
    return jsonify({'status': 'success'}), 200

if __name__ == '__main__':
    app.run()

In this example, the /webhook endpoint is defined to handle incoming POST requests. When a request is received, the JSON payload is parsed, and the event type and associated data are extracted. Based on the event type, different actions can be performed, such as logging, database updates, or triggering other integrations.

Remember to replace the example code with your own implementation based on your specific requirements and the programming language and framework you are using.

Conclusion

Webhooks in Flyflow provide a powerful way to receive real-time notifications and data about events occurring during a call. By configuring a webhook URL for your agent and implementing a webhook endpoint in your application, you can build custom integrations and perform actions based on the call events.

Flyflow supports webhooks for call_started, call_ended, and tool_call events, allowing you to track the lifecycle of a call and respond to specific actions or integrations triggered by the agent.

By leveraging webhooks, you can extend the functionality of your Flyflow-powered applications, automate processes, and create seamless integrations with other systems and services.