docs: add webhooks section to agents and LLMs documentation (#7317)

catalyst17 · catalyst17 · commit 639356071c05 · 2025-06-10T18:53:39.000Z
# [Portal] Feature: Add Webhooks Documentation for AI Agents + Example with multiple ABIs for decoding ## Notes for the reviewer Example with multiple ABIs for decoding ([related PR](https://app.graphite.dev/github/pr/thirdweb-dev/insight-service/268/fix-improve-ABI-validation-to-support-array-format)) 1. Added examples on creating events filters with multiple ABI options Also, this PR adds comprehensive documentation about using webhooks with AI agents in the Insight platform. The documentation covers: 1. Use cases for webhooks with AI agents 2. How to create and manage webhooks 3. Filtering capabilities, including support for multiple ABIs 4. Information about webhook payloads  ## Summary by CodeRabbit - **Documentation** - Added a new "Webhooks" section describing how to use webhooks with the Insight API for real-time blockchain event notifications and event-driven AI agents. - Provided use cases, filter examples, and links to detailed webhook and payload documentation. - Enhanced webhook filter documentation to clarify support for multiple ABIs, including examples for handling ERC-20 and ERC-721 Transfer events.
diff --git a/apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx b/apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx
@@ -319,6 +319,46 @@ async function safeApiCall() {
 }
 ```
 
+## Webhooks
+
+Webhooks allow you to receive notifications when specific blockchain events or transactions occur. This enables you to build event-driven AI agents that can react to on-chain activity in real-time.
+
+### Use Cases for AI Agents
+
+- **Real-time Monitoring**: An agent can monitor for specific events (e.g., a large transfer to a whale wallet) and trigger alerts or other actions.
+- **Automated Workflows**: When a specific on-chain action occurs (e.g., a new NFT is minted), an agent can automatically kick off a downstream process, like updating a database or sending a notification.
+- **Data Aggregation**: Use webhooks to feed on-chain data into a vector database or other data store for later analysis by an LLM.
+
+### Creating a Webhook
+
+Webhooks are created and managed via the Insight API. You can find more details in the [Managing Webhooks documentation](/insight/webhooks/managing-webhooks).
+
+### Filtering
+
+You can create powerful filters to specify exactly which events or transactions you want to be notified about.
+
+For example, to receive a notification for both ERC-20 and ERC-721 `Transfer` events, you can use a filter like this:
+
+```typescript
+{
+  "v1.events": {
+    "chain_ids": ["1"],
+    "signatures": [
+      {
+        "sig_hash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+        "abi": "[{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"name\":\"to\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"value\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"internalType\":\"address\",\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"address\",\"name\":\"to\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"uint256\",\"name\":\"tokenId\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"}]"
+      }
+    ]
+  }
+}
+```
+
+This allows an agent to monitor multiple token standards with a single webhook. For more on filtering, see the [Filtering documentation](/insight/webhooks/filtering).
+
+### Payload
+
+The webhook payload contains the event or transaction data. Your agent will need to parse this payload to extract the relevant information. See the [Payload documentation](/insight/webhooks/payload) for details on the payload structure.
+
 ## API Reference
 
 ### Events API
diff --git a/apps/portal/src/app/insight/agents-and-llms/page.mdx b/apps/portal/src/app/insight/agents-and-llms/page.mdx
@@ -342,6 +342,44 @@ async function safeApiCall() {
 }
 ```
 
+## Webhooks
+
+Webhooks are a powerful tool for building event-driven AI agents that can react to on-chain activity in real-time. By subscribing to specific blockchain events or transactions, your agent can receive notifications and trigger automated workflows.
+
+### Use Cases for AI Agents
+
+- **Real-time Monitoring**: An agent can monitor for specific events (e.g., a large transfer to a whale wallet) and trigger alerts or other actions.
+- **Automated Workflows**: When a specific on-chain action occurs (e.g., a new NFT is minted), an agent can automatically kick off a downstream process, like updating a database or sending a notification.
+- **Data Aggregation**: Use webhooks to feed on-chain data into a vector database or other data store for later analysis by an LLM.
+
+### Getting Started with Webhooks
+
+To get started, you can create and manage webhooks through the Insight API. For detailed instructions, refer to the [Managing Webhooks documentation](/insight/webhooks/managing-webhooks).
+
+### Filtering Events
+
+Insight's webhooks feature a powerful filtering system that lets you subscribe to only the events and transactions you care about. For example, you can create a single webhook that notifies your agent of both ERC-20 and ERC-721 `Transfer` events by providing multiple ABIs in the filter.
+
+```typescript
+{
+  "v1.events": {
+    "chain_ids": ["1"],
+    "signatures": [
+      {
+        "sig_hash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+        "abi": "[{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"name\":\"to\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"value\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"internalType\":\"address\",\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"address\",\"name\":\"to\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"uint256\",\"name\":\"tokenId\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"}]"
+      }
+    ]
+  }
+}
+```
+
+For more advanced filtering options, see the [Filtering documentation](/insight/webhooks/filtering).
+
+### Understanding the Payload
+
+When a webhook is triggered, it sends a payload to your specified endpoint. This payload contains the event or transaction data that your agent will need to process. To learn more about the structure of this payload, see the [Payload documentation](/insight/webhooks/payload).
+
 ## API Reference
 
 ### Events API
diff --git a/apps/portal/src/app/insight/webhooks/filtering/page.mdx b/apps/portal/src/app/insight/webhooks/filtering/page.mdx
@@ -30,12 +30,12 @@ Each webhook must have either an events filter or a transactions filter (or both
 ```typescript
 {
   "v1.events": {
-    chain_ids: string[],          // Filter by specific chains
-    addresses: string[],          // Filter by contract addresses
-    signatures: {                 // Filter by event signatures
-      sig_hash: string,          // Event signature hash
-      abi?: string,             // Optional ABI for data decoding
-      params?: Record<string, string | number> // Filter on decoded parameters
+    chain_ids: string[],                        // Filter by specific chains
+    addresses: string[],                        // Filter by contract addresses
+    signatures: {                               // Filter by event signatures
+      sig_hash: string,                         // Event signature hash
+      abi?: string,                             // Optional: A single ABI object or an array of ABI objects as a string for data decoding
+      params?: Record<string, string | number>  // Filter on decoded parameters
     }[]
   }
 }
@@ -45,13 +45,13 @@ Each webhook must have either an events filter or a transactions filter (or both
 ```typescript
 {
   "v1.transactions": {
-    chain_ids: string[],          // Filter by specific chains
-    from_addresses: string[],     // Filter by sender addresses
-    to_addresses: string[],       // Filter by recipient addresses
-    signatures: {                 // Filter by function signatures
-      sig_hash: string,          // Function signature hash
-      abi?: string,             // Optional ABI for data decoding
-      params?: Record<string, string | number> // Filter on decoded parameters
+    chain_ids: string[],                        // Filter by specific chains
+    from_addresses: string[],                   // Filter by sender addresses
+    to_addresses: string[],                     // Filter by recipient addresses
+    signatures: {                               // Filter by function signatures
+      sig_hash: string,                         // Function signature hash
+      abi?: string,                             // Optional: A single ABI object or an array of ABI objects as a string for data decoding
+      params?: Record<string, string | number>  // Filter on decoded parameters
     }[]
   }
 }
@@ -82,6 +82,34 @@ The following example will filter for `Transfer` events on Ethereum for the cont
 }
 ```
 
+### Supporting Multiple Event ABIs
+
+In some cases, different token standards use the same event signature. For example, both ERC-20 and ERC-721 standards have a `Transfer` event. The ERC-20 `Transfer(address,address,uint256)` event has a non-indexed `value` parameter, while the ERC-721 `Transfer(address,address,uint256)` has an indexed `tokenId` parameter.
+
+To support these scenarios, you can provide an array of ABIs in the `abi` field. This allows the webhook to attempt decoding with each ABI until one succeeds.
+
+The `abi` field accepts a string that can be either a single JSON object `"{}"` or a JSON array of objects `'[{},{}]'`.
+
+Here is an example of a webhook that filters for both ERC-20 and ERC-721 `Transfer` events across all contracts on the Ethereum mainnet:
+
+```typescript
+{
+  ...
+  "filters": {
+    "v1.events": {
+      "chain_ids": ["1"],
+      "signatures": [
+        {
+          "sig_hash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+          "abi": "[{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"name\":\"to\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"value\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":true,\"internalType\":\"address\",\"name\":\"from\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"address\",\"name\":\"to\",\"type\":\"address\"},{\"indexed\":true,\"internalType\":\"uint256\",\"name\":\"tokenId\",\"type\":\"uint256\"}],\"name\":\"Transfer\",\"type\":\"event\"}]"
+        }
+      ]
+    }
+  }
+  ...
+}
+```
+
 And this example will filter for `Approve` function calls on Ethereum for the contract `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984`
 ```typescript
 {
