Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): describe never-sent rows in JS and PHP deliveryFailures

Yudhi Armyndharis55fa51f2bf4f
diff --git a/sdk/javascript/src/resources/webhooks.ts b/sdk/javascript/src/resources/webhooks.ts
index 98a444d03..b3b217b33 100644
--- a/sdk/javascript/src/resources/webhooks.ts
+++ b/sdk/javascript/src/resources/webhooks.ts
@@ -38,11 +38,14 @@ export class WebhooksResource {
}
/**
- * Deliveries that were attempted and failed — the diagnostic to reach for when a webhook stopped
- * arriving. Requires an ADMIN-level key.
+ * Deliveries the gateway gave up on or could not dispatch: the diagnostic to reach for when a webhook
+ * stopped arriving. Rows with `attempts > 0` exhausted their retries against the receiver. Rows with
+ * `attempts === 0` were not given up after retries: the payload was over the size cap or could not be
+ * serialized after the webhook:before hooks, dispatch capacity was shed, or shutdown interrupted the
+ * delivery (possibly between retries, after earlier attempts). A row is removed once a later replay
+ * delivers the event. Requires an ADMIN-level key.
*
- * Note it records deliveries that were ATTEMPTED: a delivery a smart filter suppressed never reaches
- * this log. Most recent first.
+ * A delivery a smart filter suppressed never reaches this log. Most recent first.
*/
deliveryFailures(query?: DeliveryFailureQuery): Promise<WebhookDeliveryFailure[]> {
return this.client.request<WebhookDeliveryFailure[]>({
diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.ts
index 92c84dbe4..7c1720c28 100644
--- a/sdk/javascript/src/types.ts
+++ b/sdk/javascript/src/types.ts
@@ -987,7 +987,7 @@ export interface WebhookTestResult {
error?: string;
}
-/** A webhook delivery abandoned after every retry, as listed by the delivery-failure log. */
+/** A webhook delivery the gateway gave up on or could not dispatch, as listed by the delivery-failure log. */
export interface WebhookDeliveryFailure {
id: string;
webhookId: string;
@@ -997,12 +997,12 @@ export interface WebhookDeliveryFailure {
/** The idempotency key the receiver would have deduped on. */
idempotencyKey?: string | null;
deliveryId?: string | null;
- /** Total attempts made before giving up. */
+ /** Attempts made before giving up; 0 when the delivery was not given up after retries (see `deliveryFailures`). */
attempts: number;
/** Last HTTP status when the failure was a non-2xx response; null for a network or timeout error. */
lastStatusCode?: number | null;
lastError: string;
- /** ISO timestamp of when the delivery was finally abandoned. */
+ /** ISO timestamp of when the row was recorded. */
createdAt: string;
}
diff --git a/sdk/php/src/Resources/WebhooksResource.php b/sdk/php/src/Resources/WebhooksResource.php
index bff8fdd2d..7dfef2322 100644
--- a/sdk/php/src/Resources/WebhooksResource.php
+++ b/sdk/php/src/Resources/WebhooksResource.php
@@ -34,8 +34,13 @@ class WebhooksResource
}
/**
- * Deliveries that were ATTEMPTED and failed — the diagnostic for a webhook that stopped arriving.
- * Requires an ADMIN-level key. A delivery a smart filter suppressed never reaches this log.
+ * Deliveries the gateway gave up on or could not dispatch: the diagnostic for a webhook that
+ * stopped arriving. Rows with `attempts > 0` exhausted their retries against the receiver. Rows
+ * with `attempts === 0` were not given up after retries: the payload was over the size cap or
+ * could not be serialized after the webhook:before hooks, dispatch capacity was shed, or shutdown
+ * interrupted the delivery (possibly between retries, after earlier attempts). A row is removed
+ * once a later replay delivers the event. Requires an ADMIN-level key. A delivery a smart filter
+ * suppressed never reaches this log.
*
* @param array<string,mixed> $query Optional filter: `sessionId`, `limit`, `offset`.
*