Failure Alert Notifications

HeadlessOps delivers personalised email alerts whenever an integration run fails. Alerts are sent individually to each configured recipient, include a one-click unsubscribe link, and integrate directly with the MCP toolchain — so AI agents can configure notifications without touching the UI.

How Failure Alerts Work

When a run transitions to FAILED, the alert pipeline:

1. Resolves the alertEmailUsers list for the affected integration
2. Filters to email-verified, active users only — unverified accounts never receive alerts
3. Sends a personalised email to each recipient via Amazon SES
4. Embeds a stateless, HMAC-signed unsubscribe link in every email

Runs that fail during initial dispatch are immediately marked FAILED, ensuring alerts fire without delay regardless of where in the execution lifecycle the failure occurs.

Configuring Alert Recipients in the UI

Open the integration's Settings panel and scroll to the Alert Recipients section. Select workspace members using the card-style recipient buttons — selected users show a badge indicator.

Key behaviours:

• Only email-verified users appear as available recipients
• Selecting zero users disables email alerts for this integration
• Changes take effect immediately without requiring a push

Configuring Alert Recipients via MCP

Use the integrations_update MCP tool to configure failure alerts programmatically:

{
  "tool": "integrations_update",
  "arguments": {
    "name": "my-integration",
    "alertEmailUsers": ["user-uuid-1", "user-uuid-2"],
    "alertWebhookUrl": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
  }
}

Parameters

To retrieve user UUIDs, use the workspaces_list_users MCP tool or query the workspace members API.

Configuring Alert Recipients via REST API

curl -X PUT https://app.headlessops.ai/api/integrations/my-integration \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertEmailUsers": ["user-uuid-1", "user-uuid-2"],
    "alertWebhookUrl": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
  }'

Unsubscribing from Alerts

Every failure email includes a personalised Unsubscribe link scoped to that specific integration. Clicking it removes the recipient from alertEmailUsers for that integration — no login required, and other integrations are unaffected.

Unsubscribe Token Properties

Manual Unsubscribe via API

GET https://app.headlessops.ai/api/alerts/unsubscribe?token=<signed-token>

Returns 200 OK on success. The endpoint is public and does not require authentication.

Alert Email Content

Each failure alert email includes:

• Integration name and workspace context
• Run ID with a direct link to the run detail page
• Failure timestamp in UTC
• Error summary from the failed step output
• A personalised Unsubscribe link

Webhook Alerts

In addition to email, you can configure a alertWebhookUrl to receive a POST request whenever a run fails. The webhook payload contains the same failure metadata included in alert emails, enabling integration with Slack, PagerDuty, or any custom alerting system.

# Example: configure both email and Slack webhook alerts
curl -X PUT https://app.headlessops.ai/api/integrations/my-integration \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertEmailUsers": ["user-uuid-1"],
    "alertWebhookUrl": "https://hooks.slack.com/services/T00/B00/XXXX"
  }'

Troubleshooting

Related

• MCP Tools Reference — full list of available MCP tools including integrations_update
• Runs API — query run status and failure details programmatically
• Users and RBAC — manage workspace members and email verification