External Functions (ext_functions) Documentation

Overview

The ext_functions table is designed to manage external function (ext-function) webhooks. These webhooks allow the chatbot to trigger external processes by calling designated web endpoints. This document outlines the technical specifications for the table schema, expected JSON payloads, and integration details.

Table Schema

The table is defined in Supabase (PostgreSQL) and includes the following columns:

id: uuid, primary key generated using uuid_generate_v4().
webhook_name: text, a unique logical name for the webhook.
webhook_url: text, the endpoint URL to call.
parameters: jsonb, a JSON object defining the required parameters for the webhook call.
description: text, an optional description explaining what the function does.
headers: jsonb, optional custom HTTP headers to include in the webhook call.
active: boolean, default true, indicating whether the webhook is active.
timeout_after: integer, number of seconds to wait for the webhook response before timing out (default is 10 seconds).
num_retries: integer, number of times to retry the webhook call upon failure (default is 3).
created_at: timestamptz, timestamp for record creation (defaults to now()).
updated_at: timestamptz, timestamp for the last update (automatically updated via trigger).

A trigger is set up on the table to update the updated_at timestamp on every row update.

Integration Workflow

Lookup & Caching: - Before executing an external function call, the system checks whether the webhook_name exists in

the ext_functions table.
- To optimize performance, these entries should be cached (e.g., in memory) on application startup or periodically refreshed.
Graceful Fallback: - If an external function is not found or the entry is marked as inactive, the application must gracefully skip

executing the webhook and return a default/fallback message, ensuring the chat does not break.
Webhook Call & Standard Response: - When a message of type ext-function is processed, the application will:
- Use the cached configuration to send the defined parameters to the specified webhook_url.
- Use the additional columns (i.e., timeout_after and num_retries) to control the call’s behavior.
- The webhook is expected to respond with a standardized JSON structure in the following format:
```
{
  "result": "successful",
  "render": {
      "role": "assistant",
      "content": "Your content here",
      "type": "text",
      "metadata": {}
  }
}
```
Timeouts & Retries: - The system will enforce the timeout_after value for each webhook call. - In the event of a timeout or failure, the system will retry the webhook call the number of times specified by

num_retries.
- Detailed logging and error handling must be implemented to facilitate debugging issues with external webhooks.

Security and Deployment

Ensure that only trusted webhook URLs are stored in the table.
Validate all incoming parameters against the stored JSON schema to prevent malformed payloads.
Regularly review and update the ext_functions entries from the admin interface (manual CRUD for now).

Usage Example (Chat JSON)

When triggering an external function, the assistant sends a message like:

{
  "role": "assistant",
  "content": "Processing your request...",
  "type": "ext-function",
  "metadata": {
    "webhook_metadata": {
      "webhook_name": "tag_the_user_in_twitter_post",
      "webhook_url": "https://hook.example.com/your-webhook-endpoint",
      "parameters": {
        "first_name": "John",
        "twitter_handle": "@john_doe",
        "message": "Welcome to our community!"
      }
    }
  }
}

In this case, the system will: - Check the existence and configuration of tag_the_user_in_twitter_post in the ext_functions table. - Use the provided configuration to call the external webhook. - Display the message in content while the webhook is processing. - Once a response is received from the webhook, the chat renders the webhook’s provided render type content.

Conclusion

By using the ext_functions table and the standardized payload format, external function integrations become easier to manage, monitor, and update. This approach centralizes configuration and provides a consistent fallback and error-handling strategy, ensuring a smooth user experience even when external dependencies fail.