Public API Webhook Enhancements: Delivery Attempts, Status Reason, and Delivery Log Export

What’s New?

We’ve expanded the Public API webhook capabilities with new delivery metadata, richer event payloads, and export support for webhook delivery logs. These updates make webhook integrations easier to monitor, debug, and process safely.

What Changed?

Previously, webhook consumers did not receive a delivery-attempt header, visibility/status webhook payloads did not include a human-readable status reason, and there was no dedicated delivery-log export endpoint in the published schema. In addition, delivery log filters previously accepted single string values.

Now, the Public API includes the following webhook changes:

GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

Delivery Attempt Header

Alvys now includes an X-Alvys-Attempt header on every outbound webhook delivery request. The value represents the delivery attempt number as an integer string.

This can be used to support idempotent processing, suppress duplicate warnings, and track retry behavior.

statusReason Added to Webhook Payloads

Outbound webhook payloads for visibility and status events now include a statusReason field. This field provides the human-readable reason description, distinct from the reason code.

Example:

{
  "statusReason": "Normal Status"
}

Delivery Logs Export

A new webhook delivery log export endpoint is now available in the new schema: GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export. It supports CSV and JSON export and uses the same filters as the delivery logs list endpoint. The schema description also confirms the export supports up to 25,000 rows total.

Query Parameters

Export Behavior

The new schema documents the following format resolution behavior for the export endpoint:

1. Format=csv or Format=json in the query string takes precedence when provided.
2. Otherwise, the Accept header is used.
3. Otherwise, the response defaults to JSON.

Breaking Change: Delivery Log Filters Now Accept Arrays

The delivery logs list endpoint changed its filter shape between the old and new schema. Previously, both Status and EventType were single strings. In the new schema, both are arrays of strings.

Before

{
  "status": "failed",
  "eventType": "load.updated"
}

After

{
  "status": ["failed"],
  "eventType": ["load.updated"]
}

This change also applies to the export endpoint, where Status and EventType are defined as arrays.

Endpoints Affected

• GET /p/v{version}/webhooks/{webhookId}/delivery-logs
• GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

Why?

These enhancements provide:

• better retry visibility for webhook consumers
• clearer status context in outbound payloads
• easier export and audit of webhook delivery history
• more flexible filtering for delivery log queries and exports