Skip to content

Commit 12bcfc5

Browse files
iuwqyiriuwqyir
authored
insight webhooks docs (#6574)
1 parent a4ff738 commit 12bcfc5

File tree

5 files changed

+443
-0
lines changed

5 files changed

+443
-0
lines changed

‎apps/portal/src/app/insight/sidebar.tsx

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
Network,
1010
Rocket,
1111
StickyNote,
12+
Webhook,
1213
Wrench,
1314
} from "lucide-react";
1415

@@ -58,6 +59,33 @@ export const sidebar: SideBar = {
5859
},
5960
],
6061
},
62+
{
63+
name: "Webhooks",
64+
href: `${insightSlug}/webhooks`,
65+
icon: <Webhook />,
66+
links: [
67+
{
68+
name: "Getting Started",
69+
href: `${insightSlug}/webhooks`,
70+
},
71+
{
72+
name: "Managing Webhooks",
73+
href: `${insightSlug}/webhooks/managing-webhooks`,
74+
},
75+
{
76+
name: "Filtering",
77+
href: `${insightSlug}/webhooks/filtering`,
78+
},
79+
{
80+
name: "Payload",
81+
href: `${insightSlug}/webhooks/payload`,
82+
},
83+
{
84+
name: "API Reference",
85+
href: "https://insight-api.thirdweb.com/reference#tag/webhooks",
86+
},
87+
],
88+
},
6189
{
6290
name: "API Reference",
6391
href: "https://insight-api.thirdweb.com/reference",

‎apps/portal/src/app/insight/webhooks/filtering/page.mdx

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
import { createMetadata } from "@doc";
2+
3+
export const metadata = createMetadata({
4+
title: "Insight Webhooks | thirdweb Infrastructure",
5+
description: "Filtering",
6+
image: {
7+
title: "Insight",
8+
icon: "insight",
9+
},
10+
});
11+
12+
# Filtering
13+
14+
## Webhook Topics
15+
16+
### `v1.events`
17+
18+
Subscribes to blockchain log events.
19+
20+
### `v1.transactions`
21+
22+
Subscribes to blockchain transactions.
23+
24+
## Webhook Filters
25+
26+
You can filter webhook notifications based on specific criteria.
27+
Each webhook must have either an events filter or a transactions filter (or both).
28+
29+
### Event Filters
30+
```typescript
31+
{
32+
"v1.events": {
33+
chain_ids: string[], // Filter by specific chains
34+
addresses: string[], // Filter by contract addresses
35+
signatures: { // Filter by event signatures
36+
sig_hash: string, // Event signature hash
37+
abi?: string, // Optional ABI for data decoding
38+
params?: Record<string, any> // Filter on decoded parameters
39+
}[]
40+
}
41+
}
42+
```
43+
44+
### Transaction Filters
45+
```typescript
46+
{
47+
"v1.transactions": {
48+
chain_ids: string[], // Filter by specific chains
49+
from_addresses: string[], // Filter by sender addresses
50+
to_addresses: string[], // Filter by recipient addresses
51+
signatures: { // Filter by function signatures
52+
sig_hash: string, // Function signature hash
53+
abi?: string, // Optional ABI for data decoding
54+
params?: string[] // Filter on decoded parameters
55+
}[]
56+
}
57+
}
58+
```
59+
60+
### ABIs
61+
62+
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.
63+
64+
The following example will filter for `Transfer` events on Ethereum for the contract `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984`
65+
```typescript
66+
{
67+
...
68+
filters: {
69+
"v1.events": {
70+
chain_ids: ["1"],
71+
addresses: ["0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"],
72+
signatures: [
73+
{
74+
sig_hash:
75+
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
76+
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"}',
77+
},
78+
],
79+
},
80+
},
81+
...
82+
}
83+
```
84+
85+
And this example will filter for `Approve` function calls on Ethereum for the contract `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984`
86+
```typescript
87+
{
88+
...
89+
filters: {
90+
"v1.transactions": {
91+
chain_ids: ["1"],
92+
addresses: ["0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"],
93+
signatures: [
94+
{
95+
sig_hash: "0x095ea7b3",
96+
abi: '{"inputs":[{"internalType":"address","name":"spender","type":"address"},{"internalType":"uint256","name":"rawAmount","type":"uint256"}],"name":"approve","type":"function"}',
97+
},
98+
],
99+
},
100+
},
101+
...
102+
}
103+
```
104+
105+
### Params
106+
107+
`params` on the `signatures` object will allow you to filter based on the decoded data. Only strict equality is supported at the moment.
108+
109+
### Notes
110+
- You can specify ABIs to receive decoded event/transaction data
111+
- Parameter filtering supports equality matching only
112+
- At least one filter criteria must be specified

‎apps/portal/src/app/insight/webhooks/managing-webhooks/page.mdx

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
import { createMetadata } from "@doc";
2+
3+
export const metadata = createMetadata({
4+
title: "Insight Webhooks | thirdweb Infrastructure",
5+
description: "Managing Insight webhooks",
6+
image: {
7+
title: "Insight",
8+
icon: "insight",
9+
},
10+
});
11+
12+
# Managing Webhooks
13+
14+
For most up to date technical spec refer to https://insight-api.thirdweb.com/reference#tag/webhooks.
15+
16+
## List Webhooks
17+
`GET /v1/webhooks`
18+
19+
Retrieve all webhooks for your project or get details for a specific webhook by ID.
20+
21+
## Create Webhook
22+
`POST /v1/webhooks`
23+
24+
Creates a new webhook subscription.
25+
It may take up to a minute to start working.
26+
27+
### Verifying the created webhook
28+
- The webhook starts in a suspended state
29+
- An OTP (One-Time Password) is sent to your webhook URL for verification
30+
- You must verify the webhook within 15 minutes using the OTP
31+
- Once verified, it may take up to a minute for the webhook to become fully active
32+
- You can request a new OTP if you can't retrieve the initial OTP
33+
34+
## Update Webhook
35+
`PATCH /v1/webhooks/:webhook_id`
36+
37+
You can modify the URL or filters of a webhook. Additionally you can enable and disable the webhook.
38+
Changes may take up to a minute to take effect.
39+
40+
### Updating webhook URL
41+
- If you update the webhook URL, you'll need to verify it again with a new OTP
42+
- Other fields can be updated without requiring re-verification
43+
44+
## Delete Webhook
45+
`DELETE /v1/webhooks/:webhook_id`
46+
47+
Permanently removes a webhook subscription. This action cannot be undone.
48+
49+
## Verify Webhook
50+
`POST /v1/webhooks/:webhook_id/verify`
51+
52+
Activates a webhook using the OTP code that was sent to your webhook URL. Required for:
53+
- New webhook creation
54+
- After updating a webhook URL
55+
56+
## Resend OTP
57+
`POST /v1/webhooks/:webhook_id/resend-otp`
58+
59+
Request a new OTP code if the original expires or is lost:
60+
- Invalidates the previous OTP
61+
- New OTP expires after 15 minutes
62+
- Only works for webhooks pending verification
63+
64+
## Test Webhook
65+
`POST /v1/webhooks/test`
66+
67+
Sends a sample payload signed with a test secret ('test123').
68+
Useful for testing your receiver endpoint before creating actual webhooks.

‎apps/portal/src/app/insight/webhooks/page.mdx

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import { createMetadata } from "@doc";
2+
3+
export const metadata = createMetadata({
4+
title: "Insight Webhooks | thirdweb Infrastructure",
5+
description: "Getting started with Insight webhooks",
6+
image: {
7+
title: "Insight",
8+
icon: "insight",
9+
},
10+
});
11+
12+
# Webhooks
13+
14+
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.
15+
16+
## About Webhooks
17+
18+
### Data Delivery
19+
Webhook events are collected and delivered in batches for optimal performance and reliability. This makes webhooks ideal for:
20+
- Tracking when specific blockchain events occur
21+
- Aggregating on-chain data
22+
- Building analytics and monitoring systems
23+
- Triggering downstream processes
24+
25+
### Delivery Guarantees
26+
Events are guaranteed to be delivered *at least once*.
27+
Your application should implement idempotency and deduplication logic using the unique event ID in the payload.
28+
Events may occasionally be delivered out of order.
29+
30+
### Performance Requirements
31+
- Your receiving endpoint must respond within 3 seconds
32+
- If your endpoint consistently fails to respond in time, the webhook will be automatically suspended
33+
- We recommend implementing a queue system if you need to perform time-consuming operations

0 commit comments

Comments
 (0)