---
title: Webhook Alerting
url: "https://b13.com/products/mail-queue-for-typo3/documentation/webhook-alerting"
date: 2026-09-12
modified: 2026-09-25
lastUpdated: 2026-09-25
---

# Webhook Alerting

![Envelope icon with a circular arrow, indicating the action of replying to an email, set against a gradient background.](https://b13.com/fileadmin/_processed_/1/7/csm_sharing-ext-mail-queue-S_91a8e0ced6.webp)

 Documentation
===============

 TYPO3 Extension “Mail Queue”
 Version 1.7.0 (2026-09-12)

  **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.

     Copy

```
$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.

     Copy

```
{
  "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.](https://b13.com/fileadmin/_processed_/2/6/csm_Documentation-Images-webhook-slack-alert_87b326de24.webp)

   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.

 Webhook Alerting