feat(webhooks): add configurable retries and manual replay

Stainless-Generated-From: e8e908c91e4d4729adff54498dab7cd889708218

Author: stlc-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 41
+configured_endpoints: 45

pkg/cmd/batch.go

@@ -128,7 +128,7 @@ var batchGetResults = cli.Command{
 	HideHelpCommand: true,
 }
 
-var batchSubmit = cli.Command{
+var batchSubmit = requestflag.WithInnerFlags(cli.Command{
 	Name:    "submit",
 	Usage:   "Scrape 25K URLs or crawl large websites asynchronously.",
 	Suggest: true,
@@ -144,9 +144,14 @@ var batchSubmit = cli.Command{
 			Usage:    "Tags stored on the batch. Filter the batch list by them later.",
 			BodyPath: "tags",
 		},
+		&requestflag.Flag[map[string]any]{
+			Name:     "webhook",
+			Usage:    "Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry preserves legacy delivery; retry: {} opts into durable retries.",
+			BodyPath: "webhook",
+		},
 		&requestflag.Flag[string]{
 			Name:     "webhook-url",
-			Usage:    "URL notified when the batch finishes.",
+			Usage:    "Legacy URL notified when the batch finishes. Preserves one best-effort attempt. Cannot be combined with webhook.",
 			BodyPath: "webhookUrl",
 		},
 		&requestflag.Flag[string]{
@@ -157,7 +162,19 @@ var batchSubmit = cli.Command{
 	},
 	Action:          handleBatchSubmit,
 	HideHelpCommand: true,
-}
+}, map[string][]requestflag.HasOuterFlag{
+	"webhook": {
+		&requestflag.InnerFlag[string]{
+			Name:       "webhook.url",
+			InnerField: "url",
+		},
+		&requestflag.InnerFlag[map[string]any]{
+			Name:       "webhook.retry",
+			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.",
+			InnerField: "retry",
+		},
+	},
+})
 
 func handleBatchRetrieve(ctx context.Context, cmd *cli.Command) error {
 	client := contextdev.NewClient(getDefaultRequestOptions(cmd)...)

pkg/cmd/batch_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/context-dot-dev/context-dev-cli/internal/mocktest"
+	"github.com/context-dot-dev/context-dev-cli/internal/requestflag"
 )
 
 func TestBatchRetrieve(t *testing.T) {
@@ -85,6 +86,26 @@ func TestBatchSubmit(t *testing.T) {
 			"--input", "{data: {format: markdown, urls: [{url: https://example.com/products/anvil, itemId: sku-1, meta: {category: bar}}, {url: https://example.com/products/hammer, itemId: sku-2, meta: {foo: bar}}], options: {country: de, excludeSelectors: [x], includeHTML: true, includeImages: true, includeLinks: true, includeSelectors: [x], maxAgeMs: 0, pdf: {end: 1, ocr: true, shouldParse: true, start: 1}, settleAnimations: true, shortenBase64Images: true, useMainContentOnly: true, waitForMs: 0}}, mode: scrape}",
 			"--tag", "docs",
 			"--tag", "competitor",
+			"--webhook", "{url: https://example.com, retry: {delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}}",
+			"--webhook-url", "webhookUrl",
+			"--idempotency-key", "Idempotency-Key",
+		)
+	})
+
+	t.Run("inner flags", func(t *testing.T) {
+		// Check that inner flags have been set up correctly
+		requestflag.CheckInnerFlags(batchSubmit)
+
+		// Alternative argument passing style using inner flags
+		mocktest.TestRunMockTestWithFlags(
+			t,
+			"--api-key", "string",
+			"batch", "submit",
+			"--input", "{data: {format: markdown, urls: [{url: https://example.com/products/anvil, itemId: sku-1, meta: {category: bar}}, {url: https://example.com/products/hammer, itemId: sku-2, meta: {foo: bar}}], options: {country: de, excludeSelectors: [x], includeHTML: true, includeImages: true, includeLinks: true, includeSelectors: [x], maxAgeMs: 0, pdf: {end: 1, ocr: true, shouldParse: true, start: 1}, settleAnimations: true, shortenBase64Images: true, useMainContentOnly: true, waitForMs: 0}}, mode: scrape}",
+			"--tag", "docs",
+			"--tag", "competitor",
+			"--webhook.url", "https://example.com",
+			"--webhook.retry", "{delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}",
 			"--webhook-url", "webhookUrl",
 			"--idempotency-key", "Idempotency-Key",
 		)
@@ -128,6 +149,17 @@ func TestBatchSubmit(t *testing.T) {
 			"tags:\n" +
 			"  - docs\n" +
 			"  - competitor\n" +
+			"webhook:\n" +
+			"  url: https://example.com\n" +
+			"  retry:\n" +
+			"    delays_seconds:\n" +
+			"      - 10\n" +
+			"      - 60\n" +
+			"      - 300\n" +
+			"      - 1800\n" +
+			"      - 7200\n" +
+			"      - 21600\n" +
+			"      - 57600\n" +
 			"webhookUrl: webhookUrl\n")
 		mocktest.TestRunMockTestWithPipeAndFlags(
 			t, pipeData,

pkg/cmd/cmd.go

@@ -179,6 +179,17 @@ func init() {
 					&batchSubmit,
 				},
 			},
+			{
+				Name:     "webhooks:deliveries",
+				Category: "API RESOURCE",
+				Suggest:  true,
+				Commands: []*cli.Command{
+					&webhooksDeliveriesRetrieve,
+					&webhooksDeliveriesList,
+					&webhooksDeliveriesListAttempts,
+					&webhooksDeliveriesRetry,
+				},
+			},
 			{
 				Name:     "people",
 				Category: "API RESOURCE",

pkg/cmd/monitor.go

@@ -86,6 +86,11 @@ var monitorsCreate = requestflag.WithInnerFlags(cli.Command{
 			Usage:      "Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.",
 			InnerField: "events",
 		},
+		&requestflag.InnerFlag[map[string]any]{
+			Name:       "webhook.retry",
+			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.",
+			InnerField: "retry",
+		},
 		&requestflag.InnerFlag[string]{
 			Name:       "webhook.secret",
 			Usage:      "Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.",
@@ -185,6 +190,11 @@ var monitorsUpdate = requestflag.WithInnerFlags(cli.Command{
 			Usage:      "Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.",
 			InnerField: "events",
 		},
+		&requestflag.InnerFlag[map[string]any]{
+			Name:       "webhook.retry",
+			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.",
+			InnerField: "retry",
+		},
 		&requestflag.InnerFlag[string]{
 			Name:       "webhook.secret",
 			Usage:      "Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.",

pkg/cmd/monitor_test.go

@@ -23,7 +23,7 @@ func TestMonitorsCreate(t *testing.T) {
 			"--schedule", "{frequency: 6, type: interval, unit: hours}",
 			"--tag", "pricing",
 			"--tag", "competitor",
-			"--webhook", "{url: https://example.com/webhook, events: [change.detected, run.completed]}",
+			"--webhook", "{url: https://example.com/webhook, events: [change.detected, run.completed], retry: {delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}}",
 		)
 	})
 
@@ -47,6 +47,7 @@ func TestMonitorsCreate(t *testing.T) {
 			"--tag", "competitor",
 			"--webhook.url", "https://example.com/webhook",
 			"--webhook.events", "[change.detected, run.completed]",
+			"--webhook.retry", "{delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}",
 		)
 	})
 
@@ -75,7 +76,16 @@ func TestMonitorsCreate(t *testing.T) {
 			"  url: https://example.com/webhook\n" +
 			"  events:\n" +
 			"    - change.detected\n" +
-			"    - run.completed\n")
+			"    - run.completed\n" +
+			"  retry:\n" +
+			"    delays_seconds:\n" +
+			"      - 10\n" +
+			"      - 60\n" +
+			"      - 300\n" +
+			"      - 1800\n" +
+			"      - 7200\n" +
+			"      - 21600\n" +
+			"      - 57600\n")
 		mocktest.TestRunMockTestWithPipeAndFlags(
 			t, pipeData,
 			"--api-key", "string",
@@ -111,7 +121,7 @@ func TestMonitorsUpdate(t *testing.T) {
 			"--tag", "pricing",
 			"--tag", "competitor",
 			"--target", "{type: page, url: https://acme.com/pricing, instructions: 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', normalize_whitespace: true}",
-			"--webhook", "{url: https://example.com/webhook, events: [change.detected, run.completed]}",
+			"--webhook", "{url: https://example.com/webhook, events: [change.detected, run.completed], retry: {delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}}",
 		)
 	})
 
@@ -136,6 +146,7 @@ func TestMonitorsUpdate(t *testing.T) {
 			"--target", "{type: page, url: https://acme.com/pricing, instructions: 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', normalize_whitespace: true}",
 			"--webhook.url", "https://example.com/webhook",
 			"--webhook.events", "[change.detected, run.completed]",
+			"--webhook.retry", "{delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600]}",
 		)
 	})
 
@@ -164,7 +175,16 @@ func TestMonitorsUpdate(t *testing.T) {
 			"  url: https://example.com/webhook\n" +
 			"  events:\n" +
 			"    - change.detected\n" +
-			"    - run.completed\n")
+			"    - run.completed\n" +
+			"  retry:\n" +
+			"    delays_seconds:\n" +
+			"      - 10\n" +
+			"      - 60\n" +
+			"      - 300\n" +
+			"      - 1800\n" +
+			"      - 7200\n" +
+			"      - 21600\n" +
+			"      - 57600\n")
 		mocktest.TestRunMockTestWithPipeAndFlags(
 			t, pipeData,
 			"--api-key", "string",