Skip to content

Commit adf6783

Browse files
pepeladeirapepeladeira
authored
Sync webhook event examples with production payloads (#411)
1 parent 9db8dc9 commit adf6783

9 files changed

Lines changed: 375 additions & 65 deletions

‎docs/webhooks/events/commission-created.mdx‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ Use the `userId` field to distinguish between manual commissions from automatic
5555
<ParamField body="partner" type="object">
5656
The partner that earned the commission (id, name, email, image, country, groupId, totalClicks, totalLeads, totalSales, totalSaleAmount, totalCommissions).
5757
</ParamField>
58-
<ParamField body="customer" type="object">
59-
The customer associated with the conversion.
58+
<ParamField body="customer" type="object | null">
59+
The customer associated with the conversion. Null for click-based or custom commissions.
6060

6161
<Expandable title="customer object">
6262
<ParamField body="id" type="string">
@@ -89,6 +89,25 @@ Use the `userId` field to distinguish between manual commissions from automatic
8989
</Expandable>
9090

9191
</ParamField>
92+
<ParamField body="link" type="object | null">
93+
The referral link associated with the commission.
94+
95+
<Expandable title="link object">
96+
<ParamField body="id" type="string">
97+
Link ID.
98+
</ParamField>
99+
<ParamField body="shortLink" type="string">
100+
Full short link URL.
101+
</ParamField>
102+
<ParamField body="domain" type="string">
103+
Short link domain.
104+
</ParamField>
105+
<ParamField body="key" type="string">
106+
Short link path/slug.
107+
</ParamField>
108+
</Expandable>
109+
110+
</ParamField>
92111
</WebhookResponseBodyParameters>
93112

94113
<ResponseExample>
@@ -136,6 +155,12 @@ Use the `userId` field to distinguish between manual commissions from automatic
136155
"sales": 1,
137156
"saleAmount": 50000,
138157
"createdAt": "2025-07-16T10:48:01.739Z"
158+
},
159+
"link": {
160+
"id": "cm0lcuvtz000xcutmqw4a7wi3",
161+
"shortLink": "https://dub.sh/track-test",
162+
"domain": "dub.sh",
163+
"key": "track-test"
139164
}
140165
}
141166
}

‎docs/webhooks/events/lead-created.mdx‎

Lines changed: 97 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,87 @@ Event triggered when a [new lead is tracked](/docs/api-reference/track/lead).
2727
<ParamField body="avatar" type="string | null">
2828
URL to the customer's avatar image.
2929
</ParamField>
30+
<ParamField body="externalId" type="string">
31+
Your external customer ID, if provided when tracking.
32+
</ParamField>
33+
<ParamField body="stripeCustomerId" type="string | null">
34+
The customer's Stripe customer ID, if linked.
35+
</ParamField>
36+
<ParamField body="sales" type="number | null">
37+
Total number of sales for the customer.
38+
</ParamField>
39+
<ParamField body="saleAmount" type="number | null">
40+
Total sale amount for the customer in cents.
41+
</ParamField>
42+
<ParamField body="createdAt" type="string">
43+
ISO 8601 timestamp when the customer was first seen.
44+
</ParamField>
45+
<ParamField body="firstSaleAt" type="string | null">
46+
ISO 8601 timestamp of the customer's first sale.
47+
</ParamField>
48+
<ParamField body="subscriptionCanceledAt" type="string | null">
49+
ISO 8601 timestamp when the customer canceled their subscription, if applicable.
50+
</ParamField>
3051
</Expandable>
3152

3253
</ParamField>
3354
<ParamField body="click" type="object">
34-
The click event that led to the lead (id, url, ip, continent, country, city, device, browser, os, ua, bot, qr, referer).
55+
The click event that led to the lead.
56+
57+
<Expandable title="click object">
58+
<ParamField body="id" type="string">
59+
Unique identifier for the click.
60+
</ParamField>
61+
<ParamField body="timestamp" type="string">
62+
ISO 8601 timestamp when the click occurred.
63+
</ParamField>
64+
<ParamField body="url" type="string">
65+
The destination URL that was visited.
66+
</ParamField>
67+
<ParamField body="country" type="string">
68+
Country code (e.g. <code>US</code>).
69+
</ParamField>
70+
<ParamField body="city" type="string">
71+
City name.
72+
</ParamField>
73+
<ParamField body="region" type="string">
74+
Region or region code.
75+
</ParamField>
76+
<ParamField body="continent" type="string">
77+
Continent code (e.g. <code>NA</code>).
78+
</ParamField>
79+
<ParamField body="device" type="string">
80+
Device type (e.g. <code>Desktop</code>, <code>Mobile</code>).
81+
</ParamField>
82+
<ParamField body="browser" type="string">
83+
Browser name (e.g. <code>Chrome</code>).
84+
</ParamField>
85+
<ParamField body="os" type="string">
86+
Operating system (e.g. <code>Mac OS</code>).
87+
</ParamField>
88+
<ParamField body="ua" type="string">
89+
User agent string.
90+
</ParamField>
91+
<ParamField body="referer" type="string">
92+
Referrer hostname or <code>(direct)</code>.
93+
</ParamField>
94+
<ParamField body="refererUrl" type="string">
95+
Full referrer URL or <code>(direct)</code>.
96+
</ParamField>
97+
<ParamField body="qr" type="boolean">
98+
Whether the click came from a QR code scan.
99+
</ParamField>
100+
<ParamField body="ip" type="string">
101+
IP address of the visitor.
102+
</ParamField>
103+
</Expandable>
104+
35105
</ParamField>
36106
<ParamField body="link" type="object">
37107
The referral link the lead is associated with (full link object).
38108
</ParamField>
39109
<ParamField body="partner" type="object | null">
40-
Partner details. Only present when the link is a partner referral link (id, name, email, image, country, groupId, totalClicks, totalLeads, totalSales, totalSaleAmount, totalCommissions, etc.).
110+
Partner details. Only present when the link is a partner referral link (id, name, email, image, country, groupId, totalClicks, totalLeads, totalConversions, totalSales, totalSaleAmount, totalCommissions, etc.).
41111
</ParamField>
42112
<ParamField body="metadata" type="object | null">
43113
Optional metadata associated with the lead event.
@@ -57,33 +127,46 @@ Event triggered when a [new lead is tracked](/docs/api-reference/track/lead).
57127
"id": "oU5P0SqI8fpwx5bxw1",
58128
"name": "John",
59129
"email": "john@example.com",
60-
"avatar": "https://example.com/john.jpeg"
130+
"avatar": "https://example.com/john.jpeg",
131+
"externalId": "",
132+
"stripeCustomerId": null,
133+
"sales": 0,
134+
"saleAmount": 0,
135+
"createdAt": "2024-08-30T09:53:50.343Z",
136+
"firstSaleAt": null,
137+
"subscriptionCanceledAt": null
61138
},
62139
"click": {
63140
"id": "d0UtZqE0BZuBPrJS",
141+
"timestamp": "2024-08-30T09:53:50.343Z",
64142
"url": "https://github.com/dubinc/dub",
65-
"ip": "63.141.57.109",
66-
"continent": "NA",
67143
"country": "US",
68144
"city": "San Francisco",
145+
"region": "CA",
146+
"continent": "NA",
69147
"device": "Desktop",
70148
"browser": "Chrome",
71149
"os": "Mac OS",
72150
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
73-
"bot": false,
151+
"referer": "(direct)",
152+
"refererUrl": "(direct)",
74153
"qr": false,
75-
"referer": "(direct)"
154+
"ip": "63.141.57.109"
76155
},
77156
"link": {
78157
"id": "cm0faqkyn0001txvfwjfeq7gl",
79158
"domain": "dub.sh",
80159
"key": "79ys3WA",
81-
"externalId": null,
82160
"url": "https://github.com/dubinc/dub",
83161
"trackConversion": true,
162+
"externalId": null,
163+
"tenantId": null,
164+
"partnerId": null,
165+
"programId": null,
84166
"archived": false,
85167
"expiresAt": null,
86168
"expiredUrl": null,
169+
"disabledAt": null,
87170
"password": null,
88171
"proxy": false,
89172
"title": null,
@@ -96,6 +179,10 @@ Event triggered when a [new lead is tracked](/docs/api-reference/track/lead).
96179
"android": null,
97180
"geo": null,
98181
"publicStats": false,
182+
"folderId": null,
183+
"tagId": null,
184+
"tags": [],
185+
"webhookIds": [],
99186
"comments": null,
100187
"shortLink": "https://dub.sh/79ys3WA",
101188
"qrCode": "https://api.dub.co/qr?url=https://dub.sh/79ys3WA?qr=1",
@@ -113,6 +200,8 @@ Event triggered when a [new lead is tracked](/docs/api-reference/track/lead).
113200
"saleAmount": 0,
114201
"createdAt": "2024-08-29T13:03:59.098Z",
115202
"updatedAt": "2024-08-30T09:53:49.505Z",
203+
"projectId": null,
204+
"testVariants": null,
116205
"testCompletedAt": null,
117206
"testStartedAt": null
118207
},

‎docs/webhooks/events/link-clicked.mdx‎

Lines changed: 32 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -32,18 +32,18 @@ If you select the 3rd option, you can programmatically associate specific links
3232
<ParamField body="url" type="string">
3333
The destination URL that was visited.
3434
</ParamField>
35-
<ParamField body="ip" type="string">
36-
IP address of the visitor.
37-
</ParamField>
38-
<ParamField body="continent" type="string">
39-
Continent code (e.g. <code>NA</code>).
40-
</ParamField>
4135
<ParamField body="country" type="string">
4236
Country code (e.g. <code>US</code>).
4337
</ParamField>
4438
<ParamField body="city" type="string">
4539
City name.
4640
</ParamField>
41+
<ParamField body="region" type="string">
42+
Region or region code.
43+
</ParamField>
44+
<ParamField body="continent" type="string">
45+
Continent code (e.g. <code>NA</code>).
46+
</ParamField>
4747
<ParamField body="device" type="string">
4848
Device type (e.g. <code>Desktop</code>, <code>Mobile</code>).
4949
</ParamField>
@@ -53,14 +53,20 @@ If you select the 3rd option, you can programmatically associate specific links
5353
<ParamField body="os" type="string">
5454
Operating system (e.g. <code>Mac OS</code>).
5555
</ParamField>
56-
<ParamField body="bot" type="boolean">
57-
Whether the request was identified as a bot.
56+
<ParamField body="ua" type="string">
57+
User agent string.
58+
</ParamField>
59+
<ParamField body="referer" type="string">
60+
Referrer hostname or <code>(direct)</code>.
61+
</ParamField>
62+
<ParamField body="refererUrl" type="string">
63+
Full referrer URL or <code>(direct)</code>.
5864
</ParamField>
5965
<ParamField body="qr" type="boolean">
6066
Whether the click came from a QR code scan.
6167
</ParamField>
62-
<ParamField body="referer" type="string">
63-
Referrer URL or <code>(direct)</code>.
68+
<ParamField body="ip" type="string">
69+
IP address of the visitor.
6470
</ParamField>
6571
</Expandable>
6672

@@ -82,28 +88,33 @@ If you select the 3rd option, you can programmatically associate specific links
8288
"id": "d0UtZqE0BZuBPrJS",
8389
"timestamp": "2024-08-30T10:16:12.124Z",
8490
"url": "https://github.com/dubinc/dub",
85-
"ip": "63.141.57.109",
86-
"continent": "NA",
8791
"country": "US",
8892
"city": "San Francisco",
93+
"region": "CA",
94+
"continent": "NA",
8995
"device": "Desktop",
9096
"browser": "Chrome",
9197
"os": "Mac OS",
9298
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
93-
"bot": false,
99+
"referer": "(direct)",
100+
"refererUrl": "(direct)",
94101
"qr": false,
95-
"referer": "(direct)"
102+
"ip": "63.141.57.109"
96103
},
97104
"link": {
98105
"id": "cm0faqkyn0001txvfwjfeq7gl",
99106
"domain": "dub.sh",
100107
"key": "79ys3WA",
101-
"externalId": null,
102108
"url": "https://github.com/dubinc/dub",
103109
"trackConversion": true,
110+
"externalId": null,
111+
"tenantId": null,
112+
"partnerId": null,
113+
"programId": null,
104114
"archived": false,
105115
"expiresAt": null,
106116
"expiredUrl": null,
117+
"disabledAt": null,
107118
"password": null,
108119
"proxy": false,
109120
"title": null,
@@ -116,6 +127,10 @@ If you select the 3rd option, you can programmatically associate specific links
116127
"android": null,
117128
"geo": null,
118129
"publicStats": false,
130+
"folderId": null,
131+
"tagId": null,
132+
"tags": [],
133+
"webhookIds": [],
119134
"comments": null,
120135
"shortLink": "https://dub.sh/79ys3WA",
121136
"qrCode": "https://api.dub.co/qr?url=https://dub.sh/79ys3WA?qr=1",
@@ -133,6 +148,8 @@ If you select the 3rd option, you can programmatically associate specific links
133148
"saleAmount": 200000,
134149
"createdAt": "2024-08-29T13:03:59.098Z",
135150
"updatedAt": "2024-08-30T10:16:12.126Z",
151+
"projectId": null,
152+
"testVariants": null,
136153
"testCompletedAt": null,
137154
"testStartedAt": null
138155
}

‎docs/webhooks/events/link-created.mdx‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,16 @@ Event triggered when a [new link is created](/docs/api-reference/links/create).
6363
"id": "cm0b87844000dismqhkviju54",
6464
"domain": "dub.sh",
6565
"key": "sOvvXDT",
66-
"externalId": null,
6766
"url": "https://github.com/stack-auth/stack",
6867
"trackConversion": false,
68+
"externalId": null,
69+
"tenantId": null,
70+
"partnerId": null,
71+
"programId": null,
6972
"archived": false,
7073
"expiresAt": null,
7174
"expiredUrl": null,
75+
"disabledAt": null,
7276
"password": null,
7377
"proxy": false,
7478
"title": null,
@@ -81,8 +85,10 @@ Event triggered when a [new link is created](/docs/api-reference/links/create).
8185
"android": null,
8286
"geo": null,
8387
"publicStats": false,
88+
"folderId": null,
8489
"tagId": null,
8590
"tags": [],
91+
"webhookIds": [],
8692
"comments": null,
8793
"shortLink": "https://dub.sh/sOvvXDT",
8894
"qrCode": "https://api.dub.co/qr?url=https://dub.sh/sOvvXDT?qr=1",
@@ -100,9 +106,10 @@ Event triggered when a [new link is created](/docs/api-reference/links/create).
100106
"saleAmount": 0,
101107
"createdAt": "2024-08-26T16:41:52.084Z",
102108
"updatedAt": "2024-08-26T16:41:52.084Z",
109+
"projectId": "cm022sis60003ikt1syy7kfhl",
110+
"testVariants": null,
103111
"testCompletedAt": null,
104-
"testStartedAt": null,
105-
"projectId": "cm022sis60003ikt1syy7kfhl"
112+
"testStartedAt": null
106113
}
107114
}
108115
```

0 commit comments

Comments
 (0)