Create subscription
Alerts
Create subscription
Creates a webhook subscription for alert notifications.
**Webhook URL requirements (SSRF protection):**
- Must be HTTPS in production.
- The host must resolve to a **publicly-routable** address. URLs that resolve
to private, loopback, link-local, cloud-metadata (`169.254.169.254`),
CGNAT, or otherwise reserved ranges are rejected — at create time **and**
re-checked at delivery time. A subscription whose host later resolves to a
non-public address stops delivering and is dead-lettered with the reason on
the delivery record.
- Internal-service ports (SSH, Postgres, Redis, etc.) are blocked.
If a legitimate endpoint is being rejected, an operator can add its
`host` or `host:port` to the `WEBHOOK_SSRF_ALLOWLIST` server config. This
is operator-only configuration and is never self-service.
**IMPORTANT**: The response includes a `secret` field that is shown **only once**.
Save this secret securely - it cannot be retrieved again.
Webhooks are delivered with:
- X-MeshQu-Event: alert.created
- X-MeshQu-Alert-Id: uuid
- X-MeshQu-Tenant-Id: uuid
- X-MeshQu-Timestamp: Unix milliseconds
- X-MeshQu-Signature: sha256=<hmac>
Subscriptions filter alerts by:
- decision_types: Array of decision types to subscribe to
- severity_min: Minimum severity level (alerts with equal or higher severity are delivered)
**HMAC Signature Verification:**
All webhooks are signed. To verify:
1. Extract X-MeshQu-Timestamp and X-MeshQu-Signature headers
2. Compute: HMAC-SHA256(secret, timestamp + "." + body)
3. Compare: "sha256=" + hex(result) === X-MeshQu-Signature
4. Reject if timestamp is older than 5 minutes (replay protection)
POST
Create subscription
Authorizations
MeshQu API key passed as a bearer token: Authorization: Bearer mqu_…. Mint one in the console (Settings → API keys).
Tenant UUID for multi-tenant isolation. Required on all authenticated routes — validated before authentication (middleware/tenant.ts), so a missing or non-UUID header returns 400 (MISSING_TENANT_ID / INVALID_TENANT_ID) before the API key is checked.
Body
application/json