Failure-Rate Alerts

Configure per-endpoint failure-rate alerts to detect bad outputs early and stop bleeding traffic.

5 min read

Failure-rate alerts watch the rolling outcome counts on an endpoint and notify configured relay targets when the failure rate is too high.

Concept

For each endpoint with alerts enabled, PayloadRelay evaluates recent request outcomes over your configured rolling window and computes:

failureRatePct = (failed_requests / total_requests) * 100

Where:

total_requests excludes synthetic test outcomes (TEST_ACCEPTED, TEST_REJECTED, TEST_RATE_LIMITED).
failed_requests includes everything except ACCEPTED, EMAIL_INGESTION_ACCEPTED, FAILOVER_TRIGGERED, and the synthetic test outcomes above.

When the minimum request count and failure-rate threshold are both met, the alert fires.

Configuration

Field	Range	Description
Enabled	On / Off	Master toggle for the failure-rate alert on this endpoint.
Failure-rate threshold	0–100 %	When the rolling failure rate meets or exceeds this percent, the alert fires.
Window	1–1440 min	Rolling time window over which outcomes are counted.
Minimum requests	1–10 000	Minimum number of non-test requests that must arrive in the window before the threshold is evaluated. Prevents false alerts on low-volume endpoints.
Cooldown	0–1440 min	After an alert fires, suppress further firings for this duration while you investigate. `0` allows the next evaluation to fire again if conditions remain bad.
Auto-pause	On / Off	When enabled, a fired alert automatically pauses the endpoint for 30 minutes. Inbound traffic during auto-pause receives `503` and is logged as `PAUSED`.
Alert targets	Up to 25 relay targets in the same organization	Relay targets that receive the alert notification payload when the alert fires. Google Sheets targets are not supported for alerts.

Configure alerts from the endpoint editor.

Auto-pause behavior

If auto-pause is enabled and an alert fires, inbound relay traffic is rejected with 503 Service Unavailable and logged as outcome PAUSED for the pause duration. You can resume the endpoint manually at any time.

Cooldown semantics

After an alert fires, the configured cooldown suppresses duplicate alerts while you investigate. Alerts can fire again after the cooldown if the threshold is still met.

Alert payload

Webhook-style targets (Webhook, Slack, Discord, Microsoft Teams, PagerDuty, Telegram) receive a JSON-shaped payload with the following fields:

{
  "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>"
}

Email targets receive a rendered HTML notification with the same fields.

Test alerts

Use the Send test alert button in the editor to dispatch a synthetic alert to all configured targets. Test alerts are marked as synthetic so you can distinguish them from production alerts. If no configured target is deliverable (for example, only unconfirmed email targets), the test is rejected; transient dispatch infrastructure failures return a retryable server error.

Endpoint management — pausing and resuming endpoints.
Observability — using Activity to investigate the failures behind an alert.
Audit Log — alert configuration changes and auto-pause events appear in the audit log.

← Back to documentation