Skip to content

Commit 7fd54b9

Browse files
author
stlc-bot
committed
feat(webhooks): simplify delivery APIs
Stainless-Generated-From: 8e86d20d97155caef7882d9d77aebc214cd368e2
1 parent d366bd3 commit 7fd54b9

8 files changed

Lines changed: 86 additions & 44 deletions

File tree

‎pkg/cmd/batch.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ var batchSubmit = requestflag.WithInnerFlags(cli.Command{
170170
},
171171
&requestflag.InnerFlag[map[string]any]{
172172
Name: "webhook.retry",
173-
Usage: "Opt into durable webhook delivery. An empty object uses the default retry schedule. Omit retry to preserve legacy delivery behavior. The policy is snapshotted for each event.",
173+
Usage: "Webhook retry settings. Use {} for the default schedule.",
174174
InnerField: "retry",
175175
},
176176
},

‎pkg/cmd/brand.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ var brandRetrieveSimplified = cli.Command{
134134
},
135135
&requestflag.Flag[[]string]{
136136
Name: "tag",
137-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
137+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
138138
QueryPath: "tags",
139139
},
140140
&requestflag.Flag[string]{
@@ -177,7 +177,7 @@ var brandSearch = cli.Command{
177177
},
178178
&requestflag.Flag[[]string]{
179179
Name: "tag",
180-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
180+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
181181
QueryPath: "tags",
182182
},
183183
&requestflag.Flag[int64]{

‎pkg/cmd/industry.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ var industryRetrieveNaics = cli.Command{
3939
},
4040
&requestflag.Flag[[]string]{
4141
Name: "tag",
42-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
42+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
4343
QueryPath: "tags",
4444
},
4545
&requestflag.Flag[int64]{
@@ -77,7 +77,7 @@ var industryRetrieveSic = cli.Command{
7777
},
7878
&requestflag.Flag[[]string]{
7979
Name: "tag",
80-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
80+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
8181
QueryPath: "tags",
8282
},
8383
&requestflag.Flag[int64]{

‎pkg/cmd/monitor.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ var monitorsCreate = requestflag.WithInnerFlags(cli.Command{
8888
},
8989
&requestflag.InnerFlag[map[string]any]{
9090
Name: "webhook.retry",
91-
Usage: "Opt into durable webhook delivery. An empty object uses the default retry schedule. Omit retry to preserve legacy delivery behavior. The policy is snapshotted for each event.",
91+
Usage: "Webhook retry settings. Use {} for the default schedule.",
9292
InnerField: "retry",
9393
},
9494
&requestflag.InnerFlag[string]{
@@ -192,7 +192,7 @@ var monitorsUpdate = requestflag.WithInnerFlags(cli.Command{
192192
},
193193
&requestflag.InnerFlag[map[string]any]{
194194
Name: "webhook.retry",
195-
Usage: "Opt into durable webhook delivery. An empty object uses the default retry schedule. Omit retry to preserve legacy delivery behavior. The policy is snapshotted for each event.",
195+
Usage: "Webhook retry settings. Use {} for the default schedule.",
196196
InnerField: "retry",
197197
},
198198
&requestflag.InnerFlag[string]{

‎pkg/cmd/parse.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ var parseHandle = requestflag.WithInnerFlags(cli.Command{
6868
},
6969
&requestflag.Flag[[]string]{
7070
Name: "tag",
71-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
71+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
7272
QueryPath: "tags",
7373
},
7474
&requestflag.Flag[bool]{

‎pkg/cmd/web.go‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ var webExtractCompetitors = cli.Command{
150150
},
151151
&requestflag.Flag[[]string]{
152152
Name: "tag",
153-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
153+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
154154
QueryPath: "tags",
155155
},
156156
&requestflag.Flag[int64]{
@@ -186,7 +186,7 @@ var webExtractFonts = cli.Command{
186186
},
187187
&requestflag.Flag[[]string]{
188188
Name: "tag",
189-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
189+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
190190
QueryPath: "tags",
191191
},
192192
&requestflag.Flag[int64]{
@@ -227,7 +227,7 @@ var webExtractStyleguide = cli.Command{
227227
},
228228
&requestflag.Flag[[]string]{
229229
Name: "tag",
230-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
230+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
231231
QueryPath: "tags",
232232
},
233233
&requestflag.Flag[int64]{
@@ -300,7 +300,7 @@ var webScreenshot = requestflag.WithInnerFlags(cli.Command{
300300
},
301301
&requestflag.Flag[[]string]{
302302
Name: "tag",
303-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
303+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
304304
QueryPath: "tags",
305305
},
306306
&requestflag.Flag[int64]{
@@ -673,7 +673,7 @@ var webWebScrapeHTML = requestflag.WithInnerFlags(cli.Command{
673673
},
674674
&requestflag.Flag[[]string]{
675675
Name: "tag",
676-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
676+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
677677
QueryPath: "tags",
678678
},
679679
&requestflag.Flag[int64]{
@@ -766,7 +766,7 @@ var webWebScrapeImages = requestflag.WithInnerFlags(cli.Command{
766766
},
767767
&requestflag.Flag[[]string]{
768768
Name: "tag",
769-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
769+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
770770
QueryPath: "tags",
771771
},
772772
&requestflag.Flag[int64]{
@@ -893,7 +893,7 @@ var webWebScrapeMd = requestflag.WithInnerFlags(cli.Command{
893893
},
894894
&requestflag.Flag[[]string]{
895895
Name: "tag",
896-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
896+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
897897
QueryPath: "tags",
898898
},
899899
&requestflag.Flag[int64]{
@@ -986,7 +986,7 @@ var webWebScrapeSitemap = cli.Command{
986986
},
987987
&requestflag.Flag[[]string]{
988988
Name: "tag",
989-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
989+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
990990
QueryPath: "tags",
991991
},
992992
&requestflag.Flag[int64]{

‎pkg/cmd/webhookdelivery.go‎

Lines changed: 49 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,18 @@ import (
1616

1717
var webhooksDeliveriesRetrieve = cli.Command{
1818
Name: "retrieve",
19-
Usage: "Get the live status, retry policy, latest attempt, and replay expiration for a\nretained delivery. Use the attempts endpoint for its complete paginated history.\nThis endpoint costs no credits.",
19+
Usage: "Get a webhook delivery, including its status and latest attempt.",
2020
Suggest: true,
2121
Flags: []cli.Flag{
2222
&requestflag.Flag[string]{
2323
Name: "delivery-id",
24+
Usage: "Delivery ID.",
2425
Required: true,
2526
PathParam: "delivery_id",
2627
},
2728
&requestflag.Flag[[]string]{
2829
Name: "tag",
29-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
30+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
3031
QueryPath: "tags",
3132
},
3233
},
@@ -36,39 +37,55 @@ var webhooksDeliveriesRetrieve = cli.Command{
3637

3738
var webhooksDeliveriesList = cli.Command{
3839
Name: "list",
39-
Usage: "List retained batch and monitor webhook deliveries for your organization, newest\nfirst. Filter by at most one of batch_id, monitor_id, or run_id, optionally\ncombined with status. Historical events without retained payloads are not\nlisted. This endpoint costs no credits.",
40+
Usage: "List your batch or monitor webhook deliveries, newest first.",
4041
Suggest: true,
4142
Flags: []cli.Flag{
4243
&requestflag.Flag[string]{
43-
Name: "batch-id",
44-
QueryPath: "batch_id",
44+
Name: "type",
45+
Usage: "Delivery source.",
46+
Required: true,
47+
BodyPath: "type",
4548
},
4649
&requestflag.Flag[string]{
47-
Name: "cursor",
48-
QueryPath: "cursor",
50+
Name: "batch-id",
51+
Usage: "Filter by batch ID.",
52+
BodyPath: "batch_id",
4953
},
50-
&requestflag.Flag[int64]{
51-
Name: "limit",
52-
Default: 25,
53-
QueryPath: "limit",
54+
&requestflag.Flag[any]{
55+
Name: "created-after",
56+
Usage: "Only include events created after this ISO 8601 timestamp.",
57+
BodyPath: "created_after",
5458
},
5559
&requestflag.Flag[string]{
56-
Name: "monitor-id",
57-
QueryPath: "monitor_id",
60+
Name: "cursor",
61+
Usage: "The next_cursor from the previous response.",
62+
BodyPath: "cursor",
5863
},
59-
&requestflag.Flag[string]{
60-
Name: "run-id",
61-
QueryPath: "run_id",
64+
&requestflag.Flag[int64]{
65+
Name: "limit",
66+
Usage: "Number of deliveries to return.",
67+
Default: 25,
68+
BodyPath: "limit",
6269
},
6370
&requestflag.Flag[string]{
64-
Name: "status",
65-
Usage: `Allowed values: "pending", "delivering", "retrying", "delivered", "failed", "cancelled".`,
66-
QueryPath: "status",
71+
Name: "status",
72+
Usage: "Filter by delivery status.",
73+
BodyPath: "status",
6774
},
6875
&requestflag.Flag[[]string]{
69-
Name: "tag",
70-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
71-
QueryPath: "tags",
76+
Name: "tag",
77+
Usage: "Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.",
78+
BodyPath: "tags",
79+
},
80+
&requestflag.Flag[string]{
81+
Name: "monitor-id",
82+
Usage: "Filter by monitor ID.",
83+
BodyPath: "monitor_id",
84+
},
85+
&requestflag.Flag[string]{
86+
Name: "run-id",
87+
Usage: "Filter by monitor run ID.",
88+
BodyPath: "run_id",
7289
},
7390
},
7491
Action: handleWebhooksDeliveriesList,
@@ -77,26 +94,29 @@ var webhooksDeliveriesList = cli.Command{
7794

7895
var webhooksDeliveriesListAttempts = cli.Command{
7996
Name: "list-attempts",
80-
Usage: "List individual HTTP attempts for a delivery, newest first, including their\ndestination, timestamps, HTTP status, and error. An interrupted attempt may have\nreached the endpoint even when its outcome is unknown. This endpoint costs no\ncredits.",
97+
Usage: "List delivery attempts, newest first.",
8198
Suggest: true,
8299
Flags: []cli.Flag{
83100
&requestflag.Flag[string]{
84101
Name: "delivery-id",
102+
Usage: "Delivery ID.",
85103
Required: true,
86104
PathParam: "delivery_id",
87105
},
88106
&requestflag.Flag[string]{
89107
Name: "cursor",
108+
Usage: "The next_cursor from the previous response.",
90109
QueryPath: "cursor",
91110
},
92111
&requestflag.Flag[int64]{
93112
Name: "limit",
113+
Usage: "Number of attempts to return.",
94114
Default: 25,
95115
QueryPath: "limit",
96116
},
97117
&requestflag.Flag[[]string]{
98118
Name: "tag",
99-
Usage: "Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.",
119+
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
100120
QueryPath: "tags",
101121
},
102122
},
@@ -106,16 +126,18 @@ var webhooksDeliveriesListAttempts = cli.Command{
106126

107127
var webhooksDeliveriesRetry = cli.Command{
108128
Name: "retry",
109-
Usage: "Queue an immediate attempt without rerunning or billing the underlying batch or\nmonitor. A waiting retry is brought forward. A failed delivery gets one\nadditional attempt without restarting its automatic retry budget. Set force:\ntrue to resend an acknowledged delivery. An in-progress attempt cannot be\nduplicated. The stored event body, event ID, and creation time remain unchanged;\neach attempt receives a fresh signature. Monitor retries use the current URL and\nsecret; removing the webhook cancels pending deliveries. Batch result URLs in\nold payloads may have expired: retrieve the batch to get fresh URLs. Replay is\navailable for seven days. A successful attempt cancels remaining automatic\nretries. Idempotency-Key is scoped to your organization and retained with the\ndelivery metadata; repeating the same key and input returns the original\naccepted response.",
129+
Usage: "Retry a webhook delivery within seven days of creation.",
110130
Suggest: true,
111131
Flags: []cli.Flag{
112132
&requestflag.Flag[string]{
113133
Name: "delivery-id",
134+
Usage: "Delivery ID.",
114135
Required: true,
115136
PathParam: "delivery_id",
116137
},
117138
&requestflag.Flag[bool]{
118139
Name: "force",
140+
Usage: "Resend a delivery that already succeeded.",
119141
BodyPath: "force",
120142
},
121143
&requestflag.Flag[[]string]{
@@ -125,6 +147,7 @@ var webhooksDeliveriesRetry = cli.Command{
125147
},
126148
&requestflag.Flag[string]{
127149
Name: "idempotency-key",
150+
Usage: "Unique key to prevent duplicate retry requests.",
128151
HeaderPath: "Idempotency-Key",
129152
},
130153
},
@@ -193,7 +216,7 @@ func handleWebhooksDeliveriesList(ctx context.Context, cmd *cli.Command) error {
193216
cmd,
194217
apiquery.NestedQueryFormatBrackets,
195218
apiquery.ArrayQueryFormatComma,
196-
EmptyBody,
219+
ApplicationJSON,
197220
false,
198221
)
199222
if err != nil {

‎pkg/cmd/webhookdelivery_test.go‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,16 +29,35 @@ func TestWebhooksDeliveriesList(t *testing.T) {
2929
t,
3030
"--api-key", "string",
3131
"webhooks:deliveries", "list",
32+
"--type", "batch",
3233
"--batch-id", "batch_id",
34+
"--created-after", "'2026-09-01T00:00:00Z'",
3335
"--cursor", "whd_210b9798eb53baa4e69d31c1071cf03d",
3436
"--limit", "1",
35-
"--monitor-id", "monitor_id",
36-
"--run-id", "run_id",
3737
"--status", "pending",
3838
"--tag", "production",
3939
"--tag", "team-alpha",
4040
)
4141
})
42+
43+
t.Run("piping data", func(t *testing.T) {
44+
// Test piping YAML data over stdin
45+
pipeData := []byte("" +
46+
"type: batch\n" +
47+
"batch_id: batch_id\n" +
48+
"created_after: '2026-09-01T00:00:00Z'\n" +
49+
"cursor: whd_210b9798eb53baa4e69d31c1071cf03d\n" +
50+
"limit: 1\n" +
51+
"status: pending\n" +
52+
"tags:\n" +
53+
" - production\n" +
54+
" - team-alpha\n")
55+
mocktest.TestRunMockTestWithPipeAndFlags(
56+
t, pipeData,
57+
"--api-key", "string",
58+
"webhooks:deliveries", "list",
59+
)
60+
})
4261
}
4362

4463
func TestWebhooksDeliveriesListAttempts(t *testing.T) {

0 commit comments

Comments
 (0)