Skip to content
Channels and providers

Channels and providers

A channel is how a message reaches a person: in_app, email, push, chat, sms. (stream is a feed, not a person; see Streams.) in_app needs no setup. The others send through an integration, which is a provider plus its credentials.

Integrations

Create one with the unified endpoint:

curl -X POST localhost:3000/v1/integrations \
  -H "Authorization: ApiKey $KEY" -H 'Content-Type: application/json' \
  -d '{
    "providerId": "resend",
    "identifier": "transactional",
    "primary": true,
    "credentials": {"api_key": "re_…", "from": "Acme <noreply@acme.test>"}
  }'
FieldMeaning
providerIdThe provider. The valid values, by channel, are on the channel pages. An unknown value is a 400 that lists them.
identifierYour name for this integration, used by a step’s integration field. Lowercase letters, digits, hyphens and underscores, starting with a letter or digit (422 otherwise).
primaryPrefer this integration for its channel.
credentialsString fields; the names depend on the provider.

The response is 201 with id, providerId, channel, identifier, active, primary. Credentials are never returned.

Legacy endpoints. POST /v1/integrations/email, /push, /chat and /sms are older, channel-specific forms of create, kept for compatibility. They take a provider field and camelCase credential names (apiKey, botToken, webhookUrl, …). New code should use POST /v1/integrations.

Which integration sends

When a step has no integration, notify uses the channel’s active integrations, preferring the one marked primary, then the lowest priority, then the lowest id. A step with "integration": "transactional" uses that identifier instead. Several providers can be active for one channel at once. Deactivate one with PATCH /v1/integrations/{id}/active and {"active": false} (204).

Reading and changing

  • GET /v1/integrations, GET /v1/integrations/{id}: each returns id, providerId, channel, identifier, active, primary, priority and credentialsMasked.
  • PUT /v1/integrations/{id} with identifier, primary, priority and credentials. Send the mask value •••••• (or leave a secret field out) to keep a stored secret unchanged; only changed, non-empty values are re-encrypted.
  • DELETE /v1/integrations/{id}: 204.

credentialsMasked shows non-secret fields as stored and replaces secret fields with ••••••. A provider with no declared secret fields is masked completely.

Encryption

Credentials are JSON, sealed with AES-256-GCM under the master key before they are stored, and opened only when a message is sent. If you lose the master key, you lose the credentials. See Security.

Network safety

Providers that call a URL you supply (the webhook providers, ntfy, Mastodon, Bluesky) go through the SSRF-safe client described under HTTP request, including the NOTIFY_SSRF_ALLOWED_HOSTS allowlist.

Subscriber addresses

Email goes to subscriber.email; SMS to the subscriber’s phone once they have verified it. Push and chat providers need their own address per subscriber, stored with:

curl -X PUT localhost:3000/v1/subscribers/user-1/credentials \
  -H "Authorization: ApiKey $KEY" -H 'Content-Type: application/json' \
  -d '{"providerId": "telegram", "channel": "chat", "credentials": {"address": "123456789"}}'

The body is providerId, channel and a credentials object. The address field depends on the provider; see push and chat. It answers 204. The path segment is your subscriberId.