Webhook

Overview

The Agent Webhook Feature allows third-party systems to send real-time notifications to an AI agent when specific events occur. This feature enables external applications to trigger workflows in response to external updates, such as when data processing is complete or new information is available.

Key Use-Cases

✅ Real-Time Notifications – Notify the agent when external systems complete processing. ✅ Workflow Automation – Trigger specific agent workflows via a webhook. ✅ Secure Communication – Uses HMAC-SHA256 signatures for payload authentication.

🔹 Example: A document processing service uses a webhook to notify an AI agent once document extraction is complete, triggering a post-processing workflow in the AI agent.

Webhook Setup & Configuration

To enable webhook functionality, follow these steps:

📌 Setting Up the Webhook in AI Workbench

---

1️⃣ Navigate to AI Workbench

• Open UPTIQ Workbench and select the AI agent that should handle webhook requests.

• Go to the Triggers tab.

2️⃣ Create a Webhook (If Not Already Configured)

• Click on "Create Webhook" and select the workflow that should be executed when the webhook is triggered.

• If no workflow exists for this webhook, create a new workflow.

• Click Generate Private Key – this key will be used for signing webhook requests.

3️⃣ Download the Private Key

• If the webhook is already configured, click on "More Actions" → "Download Private Key".

• The private key will be found in the downloaded JSON file.

4️⃣ Copy the Webhook Endpoint

• The webhook endpoint will be displayed in the Triggers tab.

• This URL must be used when sending webhook requests from third-party applications.

5️⃣ Trigger the Webhook (Third-Party Integration)

• Use the webhook endpoint and private key to make a POST request with a signed payload.

• The request must include an HMAC-SHA256 signature in the x-signature header.

---

📌 Sending a Webhook Request

🔹 Method: POST 🔹 URL: Webhook endpoint copied from the Triggers tab 🔹 Headers:

• Content-Type: application/json

• x-signature: <HMAC-SHA256 signature>

---

📌 Generating the Signature (HMAC-SHA256)

To ensure secure communication, each webhook request must include a signed payload using HMAC-SHA256.

JavaScript Example to Generate a Signature

import crypto from 'crypto'; // Using Node.js crypto library

function createSignature(requestBody, privateKey) {
    const jsonPayload = JSON.stringify(requestBody, null, 0).replace(/\n/g, '');
    // Generate the signature using the SHA-256 algorithm and the private key
    const signature = crypto.createHmac('sha256', privateKey).update(jsonPayload).digest('hex');
    return signature;
}

🔹 How It Works: ✔ Converts the request body into a JSON string. ✔ Uses the private key to generate a SHA-256 HMAC signature. ✔ The generated signature must be included in the x-signature header when sending the request.

Application of the Webhook

The Agent Webhook Feature is useful in scenarios where an AI agent needs to respond to real-time external updates. Below are some key use cases:

---

1️⃣ Document Processing Completion Notification

✔ A third-party OCR/extraction service processes a document and notifies the AI agent when extraction is complete. ✔ The webhook triggers an AI workflow that summarizes the extracted text and classifies important data.

🔹 Example Workflow: 1️⃣ The OCR service completes document processing. 2️⃣ It sends a POST request to the AI agent’s webhook endpoint, including a document ID. 3️⃣ The AI agent retrieves the document, processes it, and stores relevant information in the database.

---

2️⃣ CRM System Sync for Client Updates

✔ A CRM system (e.g., Salesforce) sends a webhook notification when client details are updated. ✔ The AI agent retrieves the latest client data and updates its internal records.

🔹 Example Workflow: 1️⃣ A sales representative updates client details in the CRM. 2️⃣ The CRM system triggers a webhook to notify the AI agent. 3️⃣ The AI agent retrieves the updated data and refreshes the client summary widget.

---

3️⃣ Fraud Detection Alert for Financial Transactions

✔ A fraud detection system sends a webhook when a suspicious transaction is flagged. ✔ The AI agent analyzes the alert and generates a risk assessment report.

🔹 Example Workflow: 1️⃣ A transaction monitoring system detects fraud-like activity. 2️⃣ It triggers a webhook to notify the AI agent with transaction details. 3️⃣ The AI agent processes the data, applies risk rules, and sends an alert to the compliance team.

---

4️⃣ AI-Powered Chatbot Receiving External Events

✔ A chatbot AI receives webhook notifications from an external support ticketing system. ✔ The AI agent updates the conversation context when ticket statuses change.

🔹 Example Workflow: 1️⃣ A customer submits a support request through an external helpdesk system. 2️⃣ The helpdesk triggers a webhook when the ticket status is updated. 3️⃣ The AI agent notifies the user with real-time updates on ticket progress.

---

5️⃣ Payment Processing Update

✔ A payment gateway sends a webhook notification when a payment is processed. ✔ The AI agent validates the payment and updates account balance records.

🔹 Example Workflow: 1️⃣ A customer completes a payment via a payment processor. 2️⃣ The payment system triggers a webhook with payment confirmation details. 3️⃣ The AI agent updates the customer’s account, reflecting the new balance or transaction record.

---

Key Benefits of Webhooks in AI Agents

✅ Enables real-time communication between AI agents and external systems. ✅ Automates workflows based on real-world triggers (e.g., document processing, payments, client updates). ✅ Ensures secure and authenticated webhook calls using HMAC-SHA256.

Limitations of Webhooks

While the Agent Webhook Feature provides real-time event-driven automation, it has certain limitations that developers should be aware of when implementing it

---

No Built-in Retry Mechanism for Failed Webhooks

✔ If a webhook request fails due to a temporary issue (e.g., network failure, service downtime), the system does not retry the request automatically. ✔ The sender (third-party system) is responsible for implementing a retry mechanism if needed.

🔹 Developer Note: If webhook reliability is a concern, design third-party integrations to handle retries in case of transient failures.

---

Webhook Performance Depends on Workflow Execution Time

✔ Webhook-triggered workflows must complete processing efficiently to avoid slow response times. ✔ If a workflow takes too long to execute, it might cause delays in system updates.

🔹 Developer Note: Optimize workflow logic to ensure that webhook-triggered tasks execute quickly and do not block other processes.

---

Final Thoughts

The Agent Webhook Feature is a powerful tool for event-driven automation, allowing AI agents to interact with external systems in real time. However, proper setup, security validation, and workflow optimization are essential to ensure reliable and efficient execution.