> ## Documentation Index > Fetch the complete documentation index at: https://docs.meshqu.com/llms.txt > Use this file to discover all available pages before exploring further. # 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= 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) ## OpenAPI ````yaml /api/openapi.json post /v1/alerts/subscriptions openapi: 3.1.0 info: title: MeshQu API description: >- Governance infrastructure for policy-aware AI decisions. MeshQu does not run tools. It governs decisions about them. version: 1.9.0 contact: name: MeshQu Support email: support@meshqu.com license: name: Proprietary servers: - url: https://api.meshqu.com description: Deployed environment security: - apiKey: [] tenantId: [] tags: - name: Operations description: Health, readiness, metrics, and signing keys - name: Policies description: Policy management - name: Policy Groups description: Policy group management - name: Decisions description: Policy evaluation and recording - name: Chains description: Decision chain verification and sealing - name: Receipts description: Public receipt and bundle retrieval - name: Forms description: Attestation forms and public submission - name: Alerts description: Alert management and webhooks - name: Audit description: Audit log retrieval and verification - name: API Keys description: API key administration - name: Admin description: Tenant and platform administration - name: Dashboard description: Console dashboard data - name: Metrics description: Decision and overview metrics - name: Fields description: Field catalogue - name: Settings description: Tenant settings - name: Rule Creation Logs description: Rule authoring telemetry paths: /v1/alerts/subscriptions: post: tags: - Alerts summary: Create subscription description: >- 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= 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) operationId: postV1AlertsSubscriptions requestBody: required: true content: application/json: schema: type: object properties: url: format: uri type: string decision_types: type: array items: type: string severity_min: anyOf: - type: string enum: - low - type: string enum: - medium - type: string enum: - high - type: string enum: - critical required: - url responses: '201': description: Default Response content: application/json: schema: type: object properties: subscription: type: object properties: id: format: uuid type: string tenant_id: format: uuid type: string webhook_url: format: uri type: string decision_types: type: array items: type: string severity_min: anyOf: - type: string enum: - low - type: string enum: - medium - type: string enum: - high - type: string enum: - critical is_active: type: boolean has_secret: description: Whether HMAC signing is enabled type: boolean created_at: format: date-time type: string created_by: type: string required: - id - tenant_id - webhook_url - decision_types - severity_min - is_active - has_secret - created_at secret: description: >- Webhook secret for HMAC-SHA256 signature verification. IMPORTANT: Save this securely - it will NOT be shown again. type: string required: - subscription - secret '400': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code type: string message: description: Human-readable message type: string details: description: Additional error details required: - code - message correlation_id: description: Request correlation ID type: string required: - error '500': description: Default Response content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code type: string message: description: Human-readable message type: string details: description: Additional error details required: - code - message correlation_id: description: Request correlation ID type: string required: - error components: securitySchemes: apiKey: type: http scheme: bearer bearerFormat: mqu_ description: >- MeshQu API key passed as a bearer token: `Authorization: Bearer mqu_…`. Mint one in the console (Settings → API keys). tenantId: type: apiKey name: X-MeshQu-Tenant-Id in: header description: >- 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. ````