← Back to documentation

Failure-Rate Alerts

Set a per-endpoint failure-rate alert and optional automatic pause.

3 min read

A failure-rate alert counts the recent endpoint outcomes. It notifies the selected relay targets when the failure rate is equal to a limit or higher.

Concept#

For each endpoint with the alerts enabled, PayloadRelay counts the recent request outcomes in the configured time window, and it calculates this value:

Code Example
failureRatePct = (failed_requests / total_requests) * 100

The calculation uses these rules:

  • total_requests does not contain the synthetic test outcomes (TEST_ACCEPTED, TEST_REJECTED, TEST_RATE_LIMITED).
  • failed_requests contains the rejected outcomes and the final failed outcomes. PENDING counts in total_requests, but it is not a failure until it has a final outcome. A completed outcome, a failover outcome, and a synthetic test outcome are not failures.

PayloadRelay rounds the failure rate that it shows to two decimal places. The alert fires when the traffic reaches the minimum request count and the rounded rate reaches the threshold.

Configuration#

FieldRangeDescription
EnabledOn / OffEnables or disables the failure-rate alert for this endpoint.
Failure-rate threshold0 to 100 %The rounded rolling failure rate that fires the alert.
Window1 to 1440 minThe rolling time window for the outcome counts.
Minimum requests1 to 10,000The number of non-test requests that PayloadRelay needs before it examines the threshold. This prevents an alert for a low-volume endpoint.
Cooldown0 to 1440 minThe time in which PayloadRelay stops the duplicate alerts after an alert fires. With 0, the next examination can fire again while the condition continues.
Auto-pauseOn / OffPauses the endpoint for 30 minutes after an alert fires. During the pause, the inbound traffic receives 503 and creates no Activity row.
Alert targetsA maximum of 25 relay targets in the same organizationThe relay targets that receive the alert notification. PayloadRelay does not support a Google Sheets target for an alert.

Configure the alerts in the endpoint editor.

Auto-pause behavior#

If auto-pause is enabled and an alert fires, PayloadRelay rejects the inbound relay traffic with 503 Service Unavailable for 30 minutes. The traffic creates no Activity row. You can resume the endpoint at any time.

Cooldown semantics#

After an alert fires, the configured cooldown stops the duplicate alerts. An alert can fire again after the cooldown while the rate stays at the threshold or higher.

Alert payload#

A webhook target receives this JSON payload directly:

Code Example
{
  "event": "payloadrelay.failure_alert",
  "endpointId": "uuid",
  "endpointName": "...",
  "failureRatePct": 87.50,
  "totalRequests": 16,
  "failedRequests": 14,
  "windowMinutes": 15,
  "autoPaused": true,
  "synthetic": false,
  "firedAt": "2026-04-25T13:00:00Z",
  "dashboardUrl": "https://app.payloadrelay.com/endpoints/<id>"
}

An email target receives an HTML notification with the same fields.

A Slack, Discord, Microsoft Teams, PagerDuty, and Telegram target receives the same alert details in the delivery format of that destination. For Microsoft Teams, PayloadRelay puts the alert details in a MessageCard, and it puts the JSON details in the card text.

Test alerts#

To send a synthetic alert to all the configured targets, use the Send test alert button in the editor. PayloadRelay marks a test alert as synthetic. If no configured target can receive the alert, PayloadRelay rejects the test. If a temporary service problem stops the handoff, the request returns an error that you can retry. A successful response means that PayloadRelay gave the alert to one target as a minimum. It does not mean that a destination received the alert.

← Back to documentation