Integrations reference

Integrations send gateway events to systems outside the dashboard, such as an email when a user registers, a Slack message when a gateway is disabled, or a webhook or stream record for every policy decision. Each integration joins one endpoint, where messages go, with one event set, which events it delivers, and holds the template for the message. One endpoint or event set can serve several integrations, so a Slack channel used for gateway alerts and payment alerts is configured once.

Integrations page

Select Integrations in the sidebar. The page has three tabs, Integrations, Endpoints, and Event Sets, and one filter box that searches all three by name, description, type, and event.

Used by counts the integrations that use the endpoint or event set, and hovering over it names them. An endpoint or event set in use can’t be deleted: its delete button stays disabled and its tooltip names the integrations using it. Delete or change those integrations first. An integration whose endpoint or event set is missing shows Missing endpoint or Missing event set in red.

Every user with the User role or higher can open the page and see each endpoint’s destination. Stored credentials are never shown. Only administrators can add, change, and test endpoints, event sets, and integrations, and delete them.

Endpoints

An endpoint is where integrations deliver: an SMTP server and its recipients, a Slack incoming webhook, an HTTPS webhook, or a stream topic, with the credentials to reach it. Select Add Endpoint on the Endpoints tab.

The Configuration card below shows the fields of the selected type.

Email (SMTP)

Slack

Messages go to the channel the incoming webhook was created for in Slack.

Webhook

Every webhook request carries an X-Webhook-Timestamp header with the Unix time in seconds, and the signature covers the timestamp and the body, so a receiver can reject replayed requests. The gateway sets Content-Type, X-Webhook-Timestamp, and X-Webhook-Signature-256 itself, so Headers can’t set them, and saving an endpoint that tries to is refused.

Stream

Stored credentials

SMTP password, Incoming webhook URL, Signing secret, Headers, SASL password, and Redis URL are write-only. Once saved, the form shows A value is stored. It is never shown. with these buttons:

• Replace opens the field for a new value. Keep stored value cancels the replacement.
• Clear removes the stored value when you save, and Undo cancels that. Required fields have no Clear.

Instead of typing a value into SMTP password, Incoming webhook URL, Signing secret, SASL password, or Redis URL, pick a secret from Use a stored secret below the field. The field then holds $SECRET:<secret_id>, shown as written, and the gateway reads the secret’s current value from Secrets at each delivery. One credential can then serve several endpoints, and changing the secret’s value takes effect on the next delivery. The list offers appliance-wide secrets to users who can view secrets.

A secret that an endpoint uses can’t be deleted. The Secrets page reports the failed delete with the names of the endpoints using it. Point those endpoints at another value first.

Endpoint test

Send test on a saved endpoint, or the paper-plane icon on its row, sends the endpoint type’s default message once, without retries. Save your changes first: the test uses the saved endpoint. A successful test shows Test message sent to the endpoint name. A failed one shows Test failed: with the reason, and stays until dismissed.

Event sets

An event set picks the events an integration delivers, from the whole event catalogue. One event set can serve several integrations. Select Add Event Set on the Event Sets tab.

An event is delivered for every gateway, user, or connection point that raises it. There is no filter by resource.

While integrations use the event set, the form names them. A change that leaves one of them with template variables that no remaining event fills is refused.

Event catalogue

A SAML sign-in that creates a user raises User Registered, and one that changes the user’s role, status, or primary flag raises User Updated, before User Login.

Integrations

An integration sends the events of an event set to an endpoint. Select Add Integration on the Integrations tab.

The Template card shows its fields once an endpoint is selected, and the Governance Audit delivery card appears when the event set holds Governance Audit events.

Each event goes to every active integration whose event set holds it and whose endpoint is active. Each integration is delivered on its own, so a slow or unreachable endpoint doesn’t hold up the others. A transient failure, such as a timeout or a 5xx or 429 response, is retried up to five times with growing delays. Other failures, such as a 4xx response, aren’t retried. Governance Audit records follow their own delivery rules, described under Governance Audit delivery.

Template

The Template card shows the fields of the endpoint’s type. A field left empty sends the default shown in it, so an empty template still sends a complete message.

The default webhook and stream payload is:

{
  "event_type": "${EVENT_TYPE}",
  "event_name": "${EVENT_NAME}",
  "timestamp": "${TIMESTAMP}",
  "appliance_id": "${APPLIANCE_ID}",
  "summary": "${EVENT_SUMMARY}",
  "data": "${EVENT_DATA}"
}

In a webhook or stream payload, a string that is exactly ${EVENT_DATA} or ${AUDIT_RECORD} is sent as a JSON object. Inside other text, and in email and Slack messages, these variables are inserted as JSON text.

The Variables list beside the template shows every variable the event set’s events fill, with a description. Select one to insert it at the cursor. A template that uses a variable no event of the event set fills can’t be saved, and a warning names it. A variable with no value for the delivered event is sent empty.

Integration test

Send test in the editor, or the paper-plane icon on the integration’s row, sends one real message for one event of the event set, the one whose event ID sorts first, filled with sample values. It is delivered, not simulated. In the editor, the test sends the integration as it stands on screen, saved or not, and is unavailable while the form has a problem that would stop it being saved. A successful test shows Test message for the event sent to the endpoint name.

Governance Audit delivery

Shown when the event set holds Governance Audit events. Audit records are kept in a journal on the appliance and retried until delivered, unless these limits skip them.

Each value is a whole number of 1 or more, or empty.

• Each audit record is one delivery, so an email or Slack integration sends one message per record. Webhook and stream integrations suit busy appliances.
• Delivery is at least once, so a record can arrive more than once, for example after a restart. Every new record carries a unique event_id, so deduplicate on it at the receiver.
• A destination that stops accepting records falls behind and catches up in order once it recovers. Without delivery limits, its oldest records are skipped only when the backlog grows past its cap.
• Turning off Active on the integration or its endpoint pauses delivery. A paused integration lets go of its undelivered records, and once active again it receives only the records produced after that.
• Records leave the appliance with the caller’s email and name, request details, and the signed VP. Send them only to a destination cleared for that data.

To start an audit integration from the Audit page, select Forward records. It opens a new event set named Governance Audit with every audit event selected. Once an integration receives audit records, the button reads Forwarding to N integrations and opens the Integrations page.

Template variables

Use ${VARIABLE} in any template field. Every event fills the common variables. Each event also fills its own, and the Variables list in the editor shows exactly which ones the selected event set offers.

Common variables

Gateway events

User events

For user events, ${OLD_STATE} and ${NEW_STATE} carry only user_id, role, status, is_primary, created_at, and updated_at. Add ${USERNAME} or ${USER_EMAIL} only when the destination needs them.

Connection point events

Payment events

Governance Audit events

The default payload’s "data": "${EVENT_DATA}" already carries the full audit record, including its event_id, as a JSON object. ${AUDIT_RECORD} and ${AUDIT_VP_JWT} are large, so keep them out of email and Slack messages.

Related

• Set up event notifications: Create an endpoint, an event set, and an integration, and send a test.
• Send audit events to an external system: Deliver Governance Audit records to a SIEM, webhook, or stream.
• Audit log: How audit records are selected, journaled, and delivered.
• Secrets: Store a credential once and use it from several endpoints.