Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(webhook): describe unsent rows in the delivery-failure contract

Yudhi Armyndharis2f5fe64cf384
diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.ts
index 188305064..648585b84 100644
--- a/src/modules/webhook/dto/webhook.dto.ts
+++ b/src/modules/webhook/dto/webhook.dto.ts
@@ -361,7 +361,10 @@ export class WebhookResponseDto {
}
}
-/** A webhook delivery that exhausted every retry — the shape `GET /webhooks/delivery-failures` serves. */
+/**
+ * A webhook delivery that exhausted its retries, or one not sent (attempts 0) that the outbox replays; the
+ * shape `GET /webhooks/delivery-failures` serves. A later successful delivery removes the row.
+ */
export class WebhookDeliveryFailureDto {
@ApiProperty({ example: '0a941dac-a965-45e7-b318-74ae8be134f0' })
id!: string;
@@ -388,7 +391,10 @@ export class WebhookDeliveryFailureDto {
@ApiPropertyOptional({ type: String, nullable: true })
deliveryId?: string | null;
- @ApiProperty({ description: 'Total attempts made before giving up.', example: 5 })
+ @ApiProperty({
+ description: 'Attempts recorded for the delivery; 0 when it was shed, refused or failed before sending.',
+ example: 5,
+ })
attempts!: number;
@ApiPropertyOptional({
@@ -402,7 +408,7 @@ export class WebhookDeliveryFailureDto {
@ApiProperty({ example: 'connect ECONNREFUSED 10.0.0.1:443' })
lastError!: string;
- @ApiProperty({ type: String, format: 'date-time', description: 'When the delivery was finally abandoned.' })
+ @ApiProperty({ type: String, format: 'date-time', description: 'When the failure was first recorded.' })
createdAt!: Date;
}
diff --git a/src/modules/webhook/webhooks-list.controller.ts b/src/modules/webhook/webhooks-list.controller.ts
index 9d905a1a2..7eaf7a404 100644
--- a/src/modules/webhook/webhooks-list.controller.ts
+++ b/src/modules/webhook/webhooks-list.controller.ts
@@ -13,10 +13,13 @@ export class WebhooksListController {
@Get('delivery-failures')
@RequireRole(ApiKeyRole.ADMIN)
- @ApiOperation({ summary: 'List recently-failed webhook deliveries (all retries exhausted)' })
+ @ApiOperation({ summary: 'List failed or unsent webhook deliveries, most recent first' })
@ApiResponse({
status: 200,
- description: 'Permanently-failed webhook deliveries, most recent first',
+ description:
+ 'Deliveries that exhausted their retries (attempts > 0) and deliveries not sent (attempts 0: shed, ' +
+ 'refused at shutdown, oversize or a preflight failure; the outbox replays them). A later successful ' +
+ 'delivery removes the row. Most recent first.',
type: [WebhookDeliveryFailureDto],
})
@ApiQuery({ name: 'sessionId', required: false, description: 'Filter to a single session' })