thirdweb-dev · joaquim-verges · Mar 28, 2025 · Mar 28, 2025 · Mar 28, 2025
@@ -9,6 +9,7 @@ import {
   Network,
   Rocket,
   StickyNote,
+  Webhook,
   Wrench,
 } from "lucide-react";
 
@@ -58,6 +59,33 @@ export const sidebar: SideBar = {
         },
       ],
     },
+    {
+      name: "Webhooks",
+      href: `${insightSlug}/webhooks`,
+      icon: <Webhook />,
+      links: [
+        {
+          name: "Getting Started",
+          href: `${insightSlug}/webhooks`,
+        },
+        {
+          name: "Managing Webhooks",
+          href: `${insightSlug}/webhooks/managing-webhooks`,
+        },
+        {
+          name: "Filtering",
+          href: `${insightSlug}/webhooks/filtering`,
+        },
+        {
+          name: "Payload",
+          href: `${insightSlug}/webhooks/payload`,
+        },
+        {
+          name: "API Reference",
+          href: "https://insight-api.thirdweb.com/reference#tag/webhooks",
+        },
+      ],
+    },
     {
       name: "API Reference",
       href: "https://insight-api.thirdweb.com/reference",

@@ -0,0 +1,112 @@
+import { createMetadata } from "@doc";
+
+export const metadata = createMetadata({
+	title: "Insight Webhooks | thirdweb Infrastructure",
+	description: "Filtering",
+  image: {
+    title: "Insight",
+    icon: "insight",
+  },
+});
+
+# Filtering
+
+## Webhook Topics
+
+### `v1.events`
+
+Subscribes to blockchain log events.
+
+### `v1.transactions`
+
+Subscribes to blockchain transactions.
+
+## Webhook Filters
+
+You can filter webhook notifications based on specific criteria.  
+Each webhook must have either an events filter or a transactions filter (or both).
+
+### Event Filters
+```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, any> // Filter on decoded parameters
+    }[]
+  }
+}
+```
+
+### Transaction Filters
+```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?: string[]         // Filter on decoded parameters
+    }[]
+  }
+}
+```
+
+### ABIs
+
+You can specify partial ABIs to have decoded data sent in the webhook payload. For this you also need to give the `sig_hash` of the event or function call.
+
+The following example will filter for `Transfer` events on Ethereum for the contract `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984`
+```typescript
+{
+  ...
+  filters: {
+    "v1.events": {
+      chain_ids: ["1"],
+      addresses: ["0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"],
+      signatures: [
+        {
+          sig_hash:
+            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+          abi: '{"inputs":[{"indexed":true,"internalType":"address","name":"from","type":"address"},{"indexed":true,"internalType":"address","name":"to","type":"address"},{"indexed":false,"internalType":"uint256","name":"amount","type":"uint256"}],"name":"Transfer","type":"event"}',
+        },
+      ],
+    },
+  },
+  ...
+}
+```
+
+And this example will filter for `Approve` function calls on Ethereum for the contract `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984`
+```typescript
+{
+  ...
+  filters: {
+    "v1.transactions": {
+      chain_ids: ["1"],
+      addresses: ["0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"],
+      signatures: [
+        {
+          sig_hash: "0x095ea7b3",
+          abi: '{"inputs":[{"internalType":"address","name":"spender","type":"address"},{"internalType":"uint256","name":"rawAmount","type":"uint256"}],"name":"approve","type":"function"}',
+        },
+      ],
+    },
+  },
+  ...
+}
+```
+
+### Params
+
+`params` on the `signatures` object will allow you to filter based on the decoded data. Only strict equality is supported at the moment.
+
+### Notes
+- You can specify ABIs to receive decoded event/transaction data
+- Parameter filtering supports equality matching only
+- At least one filter criteria must be specified
@@ -0,0 +1,68 @@
+import { createMetadata } from "@doc";
+
+export const metadata = createMetadata({
+	title: "Insight Webhooks | thirdweb Infrastructure",
+	description: "Managing Insight webhooks",
+  image: {
+    title: "Insight",
+    icon: "insight",
+  },
+});
+
+# Managing Webhooks
+
+For most up to date technical spec refer to https://insight-api.thirdweb.com/reference#tag/webhooks.
+
+## List Webhooks
+`GET /v1/webhooks`
+
+Retrieve all webhooks for your project or get details for a specific webhook by ID.
+
+## Create Webhook
+`POST /v1/webhooks`
+
+Creates a new webhook subscription.  
+It may take up to a minute to start working.
+
+### Verifying the created webhook
+- The webhook starts in a suspended state
+- An OTP (One-Time Password) is sent to your webhook URL for verification
+- You must verify the webhook within 15 minutes using the OTP
+- Once verified, it may take up to a minute for the webhook to become fully active
+- You can request a new OTP if you can't retrieve the initial OTP
+
+## Update Webhook
+`PATCH /v1/webhooks/:webhook_id`
+
+You can modify the URL or filters of a webhook. Additionally you can enable and disable the webhook.  
+Changes may take up to a minute to take effect.
+
+### Updating webhook URL
+- If you update the webhook URL, you'll need to verify it again with a new OTP
+- Other fields can be updated without requiring re-verification
+
+## Delete Webhook
+`DELETE /v1/webhooks/:webhook_id`
+
+Permanently removes a webhook subscription. This action cannot be undone.
+
+## Verify Webhook
+`POST /v1/webhooks/:webhook_id/verify`
+
+Activates a webhook using the OTP code that was sent to your webhook URL. Required for:
+- New webhook creation
+- After updating a webhook URL
+
+## Resend OTP
+`POST /v1/webhooks/:webhook_id/resend-otp`
+
+Request a new OTP code if the original expires or is lost:
+- Invalidates the previous OTP
+- New OTP expires after 15 minutes
+- Only works for webhooks pending verification
+
+## Test Webhook
+`POST /v1/webhooks/test`
+
+Sends a sample payload signed with a test secret ('test123').  
+Useful for testing your receiver endpoint before creating actual webhooks. 
@@ -0,0 +1,33 @@
+import { createMetadata } from "@doc";
+
+export const metadata = createMetadata({
+	title: "Insight Webhooks | thirdweb Infrastructure",
+	description: "Getting started with Insight webhooks",
+  image: {
+    title: "Insight",
+    icon: "insight",
+  },
+});
+
+# Webhooks
+
+Webhooks allow you to receive notifications when specific blockchain events or transactions occur. This enables you to automate workflows and keep your applications in sync with on-chain activity.
+
+## About Webhooks
+
+### Data Delivery
+Webhook events are collected and delivered in batches for optimal performance and reliability. This makes webhooks ideal for:
+- Tracking when specific blockchain events occur
+- Aggregating on-chain data
+- Building analytics and monitoring systems
+- Triggering downstream processes
+
+### Delivery Guarantees
+Events are guaranteed to be delivered *at least once*.  
+Your application should implement idempotency and deduplication logic using the unique event ID in the payload.  
+Events may occasionally be delivered out of order.
+
+### Performance Requirements
+- Your receiving endpoint must respond within 3 seconds
+- If your endpoint consistently fails to respond in time, the webhook will be automatically suspended
+- We recommend implementing a queue system if you need to perform time-consuming operations