Webhook handler errors

The failure cause appears in delivery history. This page explains how Senler determines the category and what data the application handler can return.

What requires developer attention

The application list shows two separate numbers for each application: current incidents that require developer review and deliveries that did not complete successfully during the selected period. These are different metrics. A historical failure remains in analytics after it has been reviewed, while Developer review contains only current unresolved incidents. In the API, this current count is returned as developer_attention with the corresponding app_id.

The category answers who should investigate the cause:

• Application error (application). The application handler returned an error or reported a failure in its own logic. The application developer checks the handler.
• Project configuration (configuration). The installed application in a specific project is missing an account, access, or another setting. The project owner or member corrects the setting; this is not an application code defect.
• Platform error (platform). The request did not reach the application because delivery failed inside Senler. Senler resolves the cause; the application developer does not need to reconfigure anything.
• Cause not identified (unknown). The response is insufficient for reliable classification. The developer reviews the request and response manually.

application and unknown receive developer_action_required: true and contribute to the developer-review count. configuration and platform receive developer_action_required: false and do not contribute to that count.

How the category is determined

Senler does not classify an incident from only an HTTP status or error text. It applies this order:

1. If delivery fails before the external handler is called, the incident is platform.
2. If the handler returns a valid incident object, Senler uses the application or configuration category declared by the application.
3. Without an incident object, a 5xx response is classified as application.
4. Other unexplained failures are classified as unknown.

The code field does not select a category automatically. It is a stable technical identifier for a cause inside an already determined category. The retryable field separately indicates whether repeating the request without correcting its data may help. For a response without an incident object, the value is derived from the delivery result, such as a network failure, timeout, or HTTP status. In request history, the API returns the resulting incident with code, category, developer_action_required, and retryable fields. Manual resending has an additional exception for an external handler's 401 and 403 responses, described below.

How an application reports the exact cause

To avoid making Senler infer the cause from the HTTP response, an application handler can return safe JSON with an incident object. For example, a payment tool cannot find the account selected by the user in project settings:

{
  "message": "Configured Prodamus account is unavailable",
  "incident": {
    "code": "prodamus_account_unavailable",
    "category": "configuration",
    "retryable": false
  }
}

The object contract is:

• code — an optional stable machine-readable cause code from 1 to 128 characters; it starts with a Latin letter or digit and then contains only lowercase Latin letters, digits, ., _, or -; a missing or invalid code is stored as null without discarding the category;
• category — only application or configuration; Senler assigns platform and unknown itself;
• retryable — true only when retrying the same payload without changing its data is genuinely safe and may help;
• the application does not send developer_action_required; Senler derives it from the category.

category and the boolean retryable value are required. If either is missing or invalid, Senler ignores the declared object and applies its regular classification from the failure origin and HTTP status.

The message is for a person, while incident.code is for an agent, logs, and automated diagnostics. Do not put secrets, tokens, personal data, or internal stack traces in either field. Use configuration when the cause is an account or setting of a specific installation; use application when the application handler logic itself is broken.

After fixing the cause, retry delivery or resolve the incident.