Notifications API

Maintained by: Aether365 Team Audience: Developers Scope: Notification settings API endpoints

Manage email and Teams notification settings for the authenticated tenant.

Get Notification Settings

GET /tenants/me/notifications

Example Request

curl https://api.aether365.io/tenants/me/notifications \
  -H "Authorization: Bearer ak_live_..."

Example Response

{
  "success": true,
  "data": {
    "emailReports": true,
    "emailOnComplete": true,
    "emailOnFail": true,
    "teamsWebhookUrl": "https://contoso.webhook.office.com/webhookb2/...",
    "teamsOnCritical": true,
    "teamsOnComplete": true,
    "teamsOnFail": true,
    "emailOnComplete_locked": false,
    "emailOnFail_locked": false,
    "emailReports_locked": false,
    "teamsAlerts_locked": false
  }
}

Response Fields

Field	Type	Description
emailReports	boolean	Email the scan report
emailOnComplete	boolean	Send email when a scan completes successfully
emailOnFail	boolean	Send email when a scan fails
teamsWebhookUrl	string or null	Microsoft Teams incoming webhook URL
teamsOnCritical	boolean	Post to Teams on critical findings
teamsOnComplete	boolean	Post to Teams when a scan completes
teamsOnFail	boolean	Post to Teams when a scan fails
*_locked	boolean	true when your plan does not include the corresponding notification

---

Update Notification Settings

Updates notification settings. Only the fields you include are changed.

PATCH /tenants/me/notifications

Request Body

All fields are optional. Include only the fields you want to change. Accepted keys: emailReports, emailOnComplete, emailOnFail, teamsWebhookUrl, teamsOnCritical, teamsOnComplete, teamsOnFail.

Locked settings are ignored, not rejected

Unknown keys, and keys your plan does not include (the ones reported as *_locked: true), are silently ignored - the request still returns 200 with the effective settings. The webhook URL is not format-validated on this endpoint; use the test endpoint below to verify it.

{
  "emailOnComplete": true,
  "emailOnFail": true,
  "teamsWebhookUrl": "https://contoso.webhook.office.com/webhookb2/...",
  "teamsOnComplete": true,
  "teamsOnFail": false
}

Example: Disable all email notifications

curl -X PATCH https://api.aether365.io/tenants/me/notifications \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emailOnComplete": false,
    "emailOnFail": false
  }'

Example Response

Returns the full effective settings object (same shape as GET).

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid JSON body

---

Test a Teams Webhook

Sends a test message card to a Teams incoming webhook and reports whether it was accepted. Requires the Teams alerts plan feature.

POST /tenants/me/notifications/test-webhook

Request Body

Field	Type	Required	Description
teamsWebhookUrl	string	Yes	Must be an https Microsoft-hosted webhook (*.webhook.office.com or *.logic.azure.com)

Example Response

{
  "success": true,
  "data": { "ok": true }
}

Errors

Code	HTTP	Description
AUTH_INSUFFICIENT_SCOPE	403	Teams alerts require a higher plan
VALIDATION_ERROR	400	Missing or non-Microsoft webhook URL
WEBHOOK_TEST_FAILED	400	The webhook did not accept the test message