Failures & Lifecycle

When a delivery doesn't succeed, Pennylane reacts in one of two ways depending on why it failed.

Permanent failures: disabled immediately

If your endpoint responds with one of these, the failure is treated as permanent and the subscription is disabled immediately, without retries:

HTTP 401, 403, 404, or 410
A TLS/SSL error (e.g. an invalid or expired certificate)

These signal that the endpoint is gone, misconfigured, or untrusted, so retrying would not help. The subscription's disabled_reason becomes permanent_error.

Temporary failures: retried, then possibly disabled

Any other unsuccessful outcome is treated as temporary and retried with increasing back-off:

Timeouts and connection errors
HTTP 5xx
HTTP 429
Any other non-2xx response not listed as permanent above

Each consecutive failure increments a counter. A successful delivery resets that counter to zero. If deliveries keep failing over a sustained period, the subscription is disabled with disabled_reason repeated_failure.

When a subscription is disabled

Deliveries stop. enabled becomes false.
disabled_at, disabled_reason, and last_failure_status are recorded and visible via the Get / List endpoints.
The subscription owner is notified by email (except for manual disables).

Re-enabling

There is no automatic re-enable. Once you've fixed your endpoint, re-enable the subscription via the Update webhook subscription endpoint

This clears disabled_at, disabled_reason, and the failure counters, and deliveries resume immediately.

Manually disabling

To pause deliveries without deleting the subscription, update it with "enabled": false. This sets disabled_reason to manual and does not send a notification email. Re-enable the same way.

Subscription lifecycle

stateDiagram-v2
    state "Disabled (permanent_error)" as Disabled_permanent
    state "Disabled (repeated_failure)" as Disabled_repeated
    state "Disabled (manual)" as Disabled_manual

    [*] --> Enabled : POST /webhook_subscriptions
    Enabled --> Disabled_permanent : 401/403/404/410 or TLS error
    Enabled --> Disabled_repeated : too many consecutive failures
    Enabled --> Disabled_manual : PUT enabled=false
    Disabled_permanent --> Enabled : PUT enabled=true
    Disabled_repeated --> Enabled : PUT enabled=true
    Disabled_manual --> Enabled : PUT enabled=true