From 9092af7e57a807af7811b70ae98cf00c407ea73f Mon Sep 17 00:00:00 2001 From: TTyChud Date: Thu, 24 Sep 2026 19:34:11 +0530 Subject: [PATCH 1/3] feat: add webhook delivery types --- libs/shared-types/src/lib/WebhookDelivery.ts | 67 ++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 libs/shared-types/src/lib/WebhookDelivery.ts diff --git a/libs/shared-types/src/lib/WebhookDelivery.ts b/libs/shared-types/src/lib/WebhookDelivery.ts new file mode 100644 index 0000000..4e4f6d8 --- /dev/null +++ b/libs/shared-types/src/lib/WebhookDelivery.ts @@ -0,0 +1,67 @@ +/** Status of a webhook delivery. Only `pending` and `retrying` can be attempted. */ +export type WebhookDeliveryStatus = + | 'pending' + | 'retrying' + | 'succeeded' + | 'failed'; + +export type WebhookDeliveryAttemptResult = + | 'succeeded' + | 'http_error' + | 'timed_out' + | 'network_error'; + +/** One attempt to deliver an Event to a webhook endpoint. @internal */ +export interface WebhookDeliveryAttempt { + /** 1-based position in the delivery's attempt history */ + attempt_number: number; + /** Time the request was sent, in seconds since the Unix epoch */ + attempted_at: number; + /** Time the request finished, in seconds since the Unix epoch */ + completed_at: number; + result: WebhookDeliveryAttemptResult; + /** HTTP status, or null when no response was received */ + http_status: number | null; + duration_ms: number; + error: string | null; + url: string; +} + +/** + * Delivery of one Event to one webhook endpoint, persisted for every + * subscribed endpoint before the first attempt. @internal + */ +export interface WebhookDelivery { + id: string; + /** String representing the object's type. Objects of the same type share the same value. */ + object: 'webhook_delivery'; + event_id: string; + webhook_endpoint_id: string; + /** Retries stop once the delivery is `succeeded` or `failed` */ + status: WebhookDeliveryStatus; + /** Time the next attempt is due, or null when the delivery is no longer retried */ + next_attempt_at: number | null; + /** Time the first successful attempt was made, or null */ + delivered_at: number | null; + /** Time the current claim expires, or null when no worker holds it */ + claim_until: number | null; + /** Token of the worker holding the claim. A worker whose token no longer matches has lost it and cannot settle the delivery */ + claim_token: string | null; + attempts: WebhookDeliveryAttempt[]; + + /** + * The platform account that owns the Event this delivery belongs to. + * @zoneless_extension + */ + platform_account: string; +} + +/** Result of one bounded retry run. @internal */ +export interface WebhookDeliveryBatch { + object: 'webhook_delivery.batch'; + /** A claim lost to another worker counts here and in none of the outcomes below */ + processed: number; + succeeded: number; + retrying: number; + failed: number; +} From 461e87dff4beb7ab4efe3c6e9c36781f91c16523 Mon Sep 17 00:00:00 2001 From: TTyChud Date: Thu, 24 Sep 2026 19:34:11 +0530 Subject: [PATCH 2/3] feat: export the webhook delivery types --- libs/shared-types/src/lib/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/libs/shared-types/src/lib/index.ts b/libs/shared-types/src/lib/index.ts index 2382798..53c402a 100644 --- a/libs/shared-types/src/lib/index.ts +++ b/libs/shared-types/src/lib/index.ts @@ -36,4 +36,5 @@ export * from './SubscriptionItem'; export * from './Telemetry'; export * from './TopUp'; export * from './Transfer'; +export * from './WebhookDelivery'; export * from './WebhookEndpoint'; From 4f3780fe2e77c96c9dafefad4e05f04ba0bda8c0 Mon Sep 17 00:00:00 2001 From: TTyChud Date: Fri, 25 Sep 2026 18:39:58 +0530 Subject: [PATCH 3/3] docs: trim the webhook delivery type comments --- libs/shared-types/src/lib/WebhookDelivery.ts | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/libs/shared-types/src/lib/WebhookDelivery.ts b/libs/shared-types/src/lib/WebhookDelivery.ts index 4e4f6d8..b5191b1 100644 --- a/libs/shared-types/src/lib/WebhookDelivery.ts +++ b/libs/shared-types/src/lib/WebhookDelivery.ts @@ -1,4 +1,4 @@ -/** Status of a webhook delivery. Only `pending` and `retrying` can be attempted. */ +/** Status of a webhook delivery. Only `pending` and `retrying` can be claimed. */ export type WebhookDeliveryStatus = | 'pending' | 'retrying' @@ -27,32 +27,22 @@ export interface WebhookDeliveryAttempt { url: string; } -/** - * Delivery of one Event to one webhook endpoint, persisted for every - * subscribed endpoint before the first attempt. @internal - */ +/** Delivery of one Event to one webhook endpoint. @internal */ export interface WebhookDelivery { id: string; - /** String representing the object's type. Objects of the same type share the same value. */ object: 'webhook_delivery'; event_id: string; webhook_endpoint_id: string; /** Retries stop once the delivery is `succeeded` or `failed` */ status: WebhookDeliveryStatus; - /** Time the next attempt is due, or null when the delivery is no longer retried */ + /** Time the next attempt is due, or null once retries have stopped */ next_attempt_at: number | null; - /** Time the first successful attempt was made, or null */ delivered_at: number | null; - /** Time the current claim expires, or null when no worker holds it */ claim_until: number | null; - /** Token of the worker holding the claim. A worker whose token no longer matches has lost it and cannot settle the delivery */ + /** Set while a worker holds the claim; a stale token cannot settle the delivery */ claim_token: string | null; attempts: WebhookDeliveryAttempt[]; - - /** - * The platform account that owns the Event this delivery belongs to. - * @zoneless_extension - */ + /** The platform account that owns the Event. @zoneless_extension */ platform_account: string; }