Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): describe never-sent rows in Python delivery failures

Yudhi Armyndharise40355481273
diff --git a/sdk/python/openwa/resources/webhooks.py b/sdk/python/openwa/resources/webhooks.py
index 3d4907177..09240ebd4 100644
--- a/sdk/python/openwa/resources/webhooks.py
+++ b/sdk/python/openwa/resources/webhooks.py
@@ -45,7 +45,11 @@ class WebhooksResource:
return self._http.request("GET", "/api/webhooks", query=query)
def delivery_failures(self, query: DeliveryFailureQuery | None = None) -> list[WebhookDeliveryFailure]:
- """Deliveries that were ATTEMPTED and failed -- the diagnostic for a webhook that stopped arriving.
+ """Deliveries the gateway gave up on or could not send -- the diagnostic for a webhook that stopped arriving.
+
+ Rows with ``attempts > 0`` exhausted their retries against the receiver; rows with ``attempts == 0``
+ were never sent (payload over the size cap, a payload that could not be prepared or serialized,
+ dispatch capacity shed, or shutdown). 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. Most
recent first.
diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.py
index 21296608f..7d673c261 100644
--- a/sdk/python/openwa/types.py
+++ b/sdk/python/openwa/types.py
@@ -953,7 +953,7 @@ class WebhookDelivery(TypedDict):
class WebhookDeliveryFailure(TypedDict):
- """A webhook delivery abandoned after every retry, as listed by the delivery-failure log."""
+ """A webhook delivery that exhausted its retries or was never sent, as listed by the delivery-failure log."""
id: str
webhookId: str
@@ -963,12 +963,12 @@ class WebhookDeliveryFailure(TypedDict):
# The idempotency key the receiver would have deduped on.
idempotencyKey: NotRequired[str | None]
deliveryId: NotRequired[str | None]
- # Total attempts made before giving up.
+ # Attempts recorded; 0 when the delivery was shed, refused or failed before sending.
attempts: int
# Last HTTP status when the failure was a non-2xx response; None for a network or timeout error.
lastStatusCode: NotRequired[int | None]
lastError: str
- # ISO timestamp of when the delivery was finally abandoned.
+ # ISO timestamp of when the failure was first recorded.
createdAt: str