Webhook Alerting

Chapters of this Documentation

Strongly recommended for production. The failed-mail notification (opsNotificationEmail) is itself an email—and when the queue is red, SMTP is usually the broken part, so that alarm may never leave the box.

Setup

Configure alertWebhookUrl to an HTTPS endpoint: a Slack incoming webhook, a Teams flow, or a custom receiver.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['mail_queue']['alertWebhookUrl']
    = getenv('MAIL_QUEUE_ALERT_WEBHOOK');

Prefer https:// only. The URL is admin-controlled and called from the server, which is an SSRF surface if it is mis-set to an internal http:// address.

What Fires and When

mailqueue:flush POSTs a JSON notification over that channel whenever the queue health turns red, and—unless disabled via notifyOnRecovery—again when it recovers. The call is independent of the mail transport, which is the whole point.

Notifications fire on state transitions only, tracked in sys_registry. An outage lasting hours produces one alert and one recovery message, not one per minute. There is one delivery attempt per transition; failures are logged and never interrupt queue processing.

Hold and resume each announce themselves once over the same channel.

Payload

The payload is Slack-compatible—the text key is rendered as-is by Slack incoming webhooks—and carries structured fields for other receivers.

{
  "text": "🔴 Mail queue ALERT on My Site: 3 mail(s) queued, oldest undelivered for 42 min (threshold 30 min)",
  "level": "alert",
  "pending": 3,
  "failed": 0,
  "oldestPendingMinutes": 42,
  "thresholdMinutes": 30,
  "site": "My Site"
}

level is the health state: alert, warning, or ok. Hold and resume events use hold and resume instead.

In a Slack channel the text key is what an operator actually sees—one line when the queue turns red, one when it recovers, and nothing in between:

Two messages from the Mail Queue webhook in a Slack channel: a red alert that one mail has been queued for 31 minutes against the 30 minute threshold, and 35 minutes later the green recovery message that all mails were delivered.

One Receiver Only

alertWebhookUrl takes a single URL. If the agency running the site and the customer's own IT need separate channels—Slack on one side, Teams on the other—you currently need a relay in between that fans the call out.

Mind that such a relay is another service that can fail, in a chain whose whole point is to be independent of the failing mail path. Where that matters, keep the webhook pointed at the party that actually operates the mail server.

Threshold

alertThresholdMinutes decides when health turns red—30 minutes by default. The same threshold drives the dashboard widget, so the widget and the webhook never disagree.

Tune it to your delivery expectations rather than to your tolerance for noise: because alerts fire on transitions only, a lower threshold does not produce repeated messages.