# 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**

```javascript
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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uptiq.ai/core-concepts/agent/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.