POST /v1/config/notifications

Creates a new notification channel for the current project. Once created and active, analyses whose severity meets the channel's threshold will be delivered to it.

For per-platform setup walkthroughs (where to obtain webhook URLs, how to configure recipients), see the channels guide.

Authentication

API key with config:write permission. Project-scoped or tenant-scoped (with X-Project-Id).

Endpoint

POST /v1/config/notifications

Request body

Field	Type	Required	Notes
`type`	`'slack' \| 'teams' \| 'discord' \| 'google_chat' \| 'webhook' \| 'email'`	✓	Destination platform
`name`	string (1–255 chars)	✓	Descriptive label, e.g. `#engineering-alerts`
`credentials`	object	✓	Platform-specific connection info — see below
`severityThreshold`	`'critical' \| 'high' \| 'medium' \| 'low'`	✓	Lowest severity that should fire this channel

`credentials` per type

The credentials shape depends on type:

Slack

Field	Type	Required	Notes
`webhookUrl`	string	✓	Slack incoming webhook URL

{ "webhookUrl": "https://hooks.slack.com/services/T.../B.../..." }

Microsoft Teams

Field	Type	Required	Notes
`webhookUrl`	string	✓	Office 365 connector webhook URL

{ "webhookUrl": "https://outlook.office.com/webhook/..." }

Discord

Field	Type	Required	Notes
`webhookUrl`	string	✓	Discord channel webhook URL

{ "webhookUrl": "https://discord.com/api/webhooks/..." }

Google Chat

Field	Type	Required	Notes
`webhookUrl`	string	✓	Google Chat space webhook URL

{ "webhookUrl": "https://chat.googleapis.com/v1/spaces/.../messages?key=..." }

Webhook (generic HTTPS)

Field	Type	Required	Notes
`url`	string	✓	HTTPS endpoint that will receive the payload
`authHeader`	string	—	Full `Authorization` header value, e.g. `Bearer <token>`
`hmacSecret`	string	—	Signing secret used to HMAC-SHA256 each request

{
  "url": "https://example.com/sigsentry",
  "authHeader": "Bearer abc123",
  "hmacSecret": "your-32-byte-secret"
}

When hmacSecret is set, every delivery includes an X-SigSentry-Signature: sha256=<hex> header computed over the raw request body. Generate a high-entropy secret on your side (openssl rand -hex 32) and verify on receipt — see Outgoing webhooks for the verification pattern and the full payload reference.

Email

Field	Type	Required	Notes
`recipients`	string \| string[]	✓	Comma-separated list of emails, or an array

{ "recipients": "alice@example.com, bob@example.com" }

Full request example

{
  "type": "slack",
  "name": "#engineering-alerts",
  "credentials": {
    "webhookUrl": "https://hooks.slack.com/services/T.../B.../..."
  },
  "severityThreshold": "high"
}

Response

201 Created

{
  "success": true,
  "data": {
    "id": "9b7a3b2c-2e6e-4f1f-8c5a-1b2c3d4e5f6a"
  }
}

Field	Notes
`id`	The new channel id — use it to update or delete

Credentials are stored encrypted and never returned by the API after creation. Keep a copy of any HMAC secret you generated; if you lose it, rotate it via PUT /v1/config/notifications/{id}.

Error responses

Status	`error.code`	When
400	`VALIDATION_ERROR`	Body failed validation (missing fields, bad type, name too long)
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key lacks `config:write`
403	`QUOTA_EXCEEDED`	Plan's per-project channel limit reached

Example

curl -X POST https://api.sigsentry.com/v1/config/notifications \
  -H "Authorization: Bearer ss_secret_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "name": "#engineering-alerts",
    "credentials": { "webhookUrl": "https://hooks.slack.com/services/T.../B.../..." },
    "severityThreshold": "high"
  }'

Quotas

The number of channels per project depends on your plan — see Notification Channels → Quotas.

POST /v1/config/notifications

On this page