Set up event notifications

By the end of this guide, you will have at least one event notification configured and delivering alerts to an external service when a gateway event fires.

Event notifications send structured payloads to email, Slack, a webhook, or a streaming platform when selected gateway events occur. You configure one on a single Add integration form: the integration type, category, name, description, and the type-specific fields all appear on the same page, and there is no separate step or page per type. For background on the event model and supported categories, see Event notifications.

Without notifications, there is no automated alert path for critical gateway events such as connection point changes or user additions. You must poll the dashboard or logs manually to detect them.

Use this guide when:

• You need automated alerts when specific gateway events occur.
• You are routing event data to an external monitoring or communication platform.

Prerequisites

• Dashboard access with Power User or Administrator role.
• Credentials for the target delivery service: SMTP server details, a Slack incoming webhook URL, an HTTPS endpoint, or streaming platform connection details.

Steps

Open the integration form

In the dashboard sidebar, select Integrations, then select Add Integration.

Select the integration type and category

1. From the Integration Type dropdown, select Email, Slack, Webhook, or Stream. The fields further down the form update immediately to match your selection.
2. From the Category dropdown, select the event category this integration should respond to. The options come from your gateway’s own configuration, so the list can differ between deployments. See Event categories for the illustrative default set.

Name the integration

Enter an Integration Name and, optionally, a Description.

Complete the type-specific fields

Fill in the fields shown for the integration type you selected in step 2.

For Email, the form shows:

Field	Required	Description
Subject	Yes	The email subject line. Supports ${VARIABLE_NAME} syntax.
Email Format	Yes	HTML or Plain Text. Defaults to HTML.
Body	Yes	The email body. Supports ${VARIABLE_NAME} syntax.
SMTP Host	Yes	Your SMTP server hostname.
Port	Yes	Typically 587 for STARTTLS or 465 for TLS.
Username	Yes	SMTP authentication username.
Password	Yes	SMTP authentication password.
From Address	Yes	The sender email address.
Recipient Email(s)	Yes	One or more recipient addresses, one per line or comma-separated.
Use TLS	No	Enable for connections on port 465.
Use STARTTLS	No	Enable for connections on port 587.

For Slack, the form shows:

Field	Required	Description
Message Text	Yes	The Slack message body. Supports Slack mrkdwn formatting and ${VARIABLE_NAME} syntax.
Bot Name	No	Display name for the bot.
Icon Emoji	No	An emoji icon, for example :bell:.
Channel Override	No	Override the webhook’s default channel, for example #alerts.
Webhook URL	Yes	Your Slack incoming webhook URL.

For Webhook, the form shows:

Field	Required	Description
Webhook URL	Yes	The HTTPS endpoint that receives the event payload.
HTTP Method	No	POST, PUT, or PATCH. Defaults to POST.
Signing Secret	No	Pre-filled with a random value the gateway uses to sign each request with HMAC-SHA256. Select the regenerate icon next to the field for a new value, or enter your own.
Custom Headers	No	Additional HTTP headers to send with each delivery, as a JSON object.
Payload Template	Yes	The JSON payload sent to your endpoint. Pre-filled with a default template; edit it to match what your endpoint expects.

When a signing secret is set, each request includes an X-Webhook-Signature-256: sha256=<hex> header and an X-Webhook-Timestamp header, so your endpoint can confirm authenticity.

For Stream, the form shows:

Field	Required	Description
Streaming Platform	Yes	Apache Kafka, AWS Kinesis, Apache Pulsar, or Redis Streams.
Topic/Stream Name	Yes	The topic (Kafka, Pulsar) or stream (Kinesis, Redis Streams) name to publish events to.
Event Payload Template	Yes	The JSON template for events published to the stream. Pre-filled with a default template.

Selecting Apache Kafka or Apache Pulsar adds a required Broker URLs field and an optional Authentication Type (None or SASL/PLAIN, with SASL Username and SASL Password fields when SASL/PLAIN is selected). Selecting AWS Kinesis adds a required AWS Region field and optional AWS Access Key and AWS Secret Key fields; the gateway uses its IAM role if you leave the access key blank. Selecting Redis Streams adds a required Redis URL field.

See the Integrations reference for the complete field list, including data types.

Secret hygiene

The Password, Signing Secret, SASL Password, and AWS Secret Key fields store the credential value directly in the integration’s configuration; Integrations does not reference the gateway’s centralised Secrets store. Never paste a live credential value into shared documentation, tickets, or screenshots. If a credential is compromised, rotate it at its source system (SMTP account, Slack app, or cloud IAM) and update the integration with the new value, and confirm the value is never echoed back in dashboard error messages or logs.

Create the integration

Select Create integration.

Template variables

Content fields (Subject, Body, Message Text, Payload Template, Event Payload Template) support ${VARIABLE_NAME} syntax. A variable not available for the selected category resolves to an empty string.

The following variables are available regardless of category:

Each category adds its own variables on top of this set, for example ${USER_EMAIL} for the User category or ${GATEWAY_DID} for the Gateway category. See Runtime variables for the full list per category.

Confirm

Test 1: integration status shows ACTIVE

After you select Create integration, the dashboard returns you to the Integrations list. Find the new integration by name. Its status column shows ACTIVE.

Test 2: a test notification is delivered

1. On the integration row, in the Actions column, select the paper-plane icon (tooltip: Test).
2. In the test dialog, fill in values for any variables shown, then select Send Test.

This sends a real notification using the values you provide; it is not a dry run.

Expected: the dialog reports a successful delivery, and the notification appears in the target service: inbox, Slack channel, webhook endpoint, or stream.

If the test fails, the dialog shows the error returned by the target service. Check the configuration fields and confirm network access from the gateway host to the target service.

Delivery failures triggered by real events (not the manual test) are retried with exponential backoff, so a transient outage at the destination does not drop a notification.

Troubleshooting

Next steps

• Connect two gateways: attach the integration to a connection point to receive alerts on connection events.
• Event notifications: background on the event model and how categories map to event types.

Related

• Integrations reference: full field list, event categories, and the complete runtime variables catalogue.