# Integrations reference

> Field-level reference for event-driven integrations: email, Slack, webhook, and stream.
Integrations fire when system events occur. An integration entry binds an event category to a delivery target (email, Slack, webhook, or stream) with a configurable content template.

## Integration types

All integration types share these common fields:

| Field | Type | Required | Description |
| Category | string | Yes | The event category that triggers this integration. See [Event categories](#event-categories). |
| Integration Name | string | Yes | Display name for the integration. |
| Description | string | No | Optional description. |

### Email

Send notifications via SMTP when events occur.

| Field | Type | Required | Description |
| From Address | string | Yes | Sender email address. |
| Recipient Email(s) | string | Yes | Recipient email addresses. One per line or comma-separated. |
| SMTP Host | string | Yes | SMTP server hostname. |
| Port | number | Yes | SMTP server port. Usually 587 (STARTTLS) or 465 (TLS). |
| Username | string | No | SMTP authentication username. |
| Password | string | No | SMTP authentication password. |
| Use TLS | bool | No | Enable TLS encryption. Use with port 465. |
| Use STARTTLS | bool | No | Enable STARTTLS. Use with port 587. |
| Subject | string | Yes | Email subject. Supports [runtime variables](#runtime-variables). |
| Email Format | string | Yes | HTML or Plain text. |
| Body | string | Yes | Email body. Supports HTML and [runtime variables](#runtime-variables). |

### Slack

Post messages to Slack channels via incoming webhooks.

| Field | Type | Required | Description |
| Webhook URL | string | Yes | Slack incoming webhook URL. |
| Message Text | string | Yes | Message body. Supports Slack mrkdwn formatting and [runtime variables](#runtime-variables). |
| Bot Name | string | No | Display name for the bot. |
| Icon Emoji | string | No | Emoji icon for the bot, for example :bell:. |
| Channel Override | string | No | Override the default webhook channel, for example #alerts. |

### Webhook

Send HTTP POST requests to any endpoint.

| Field | Type | Required | Description |
| Webhook URL | string | Yes | Target HTTP endpoint. |
| HTTP Method | string | No | POST, PUT, or PATCH. Defaults to POST. |
| Signing Secret | string | No | HMAC-SHA256 signing key. When set, the gateway sends an X-Webhook-Signature-256: sha256=<hex> header with each delivery. Auto-generated if left blank. |
| Custom Headers | string | No | Additional HTTP headers as a JSON map. |
| Payload Template | string | Yes | JSON payload template. Supports [runtime variables](#runtime-variables). |

### Stream

Stream events to enterprise messaging platforms.

Common stream fields:

| Field | Type | Required | Description |
| Streaming Platform | string | Yes | Kafka, Kinesis, Pulsar, or Redis. |
| Topic/Stream Name | string | Yes | The topic or stream name to publish events to. |
| Event Payload Template | string | Yes | JSON template for published events. Supports [runtime variables](#runtime-variables). |

Kafka and Pulsar additional fields:

| Field | Type | Required | Description |
| Broker URLs | string | Yes | Comma-separated broker addresses. |
| Authentication Type | string | No | None or SASL. |
| SASL Username | string | No | SASL authentication username. |
| SASL Password | string | No | SASL authentication password. |

Kinesis additional fields:

| Field | Type | Required | Description |
| AWS Region | string | Yes | AWS region where the Kinesis stream is located. |
| AWS Access Key | string | No | Uses IAM role if not provided. |
| AWS Secret Key | string | No | AWS secret access key. |

Redis Streams additional fields:

| Field | Type | Required | Description |
| Redis URL | string | Yes | Redis connection URL. Supports redis:// and rediss:// schemes. |

## Event categories

The Category dropdown determines which events trigger an integration.

| Category | Events triggered |
| General | All events across all entities. |
| User | user.created, user.approved, user.updated, user.deleted, user.login, user.accessed |
| Gateway | gateway.created, gateway.updated, gateway.deleted, gateway.status_changed, gateway.accessed |
| Connection Point | connection_point.created, connection_point.updated, connection_point.deleted, connection_point.connected, connection_point.error |
| Channel | channel.created, channel.updated, channel.deleted, channel.accessed, channel.error |
| Identity | identity.created, identity.updated, identity.deleted, identity.appeared, identity.accessed |
| MCP Proxy | mcp_proxy.created, mcp_proxy.updated, mcp_proxy.deleted, mcp_proxy.status_changed |
| Mediator | Mediator lifecycle events. |
| Trust Registry | Trust registry lifecycle events. |
| x402 | x402 payment events. |

## Runtime variables

Use ${VARIABLE} syntax in content fields. Variables are resolved when the event fires.

### Common variables

| Variable | Description |
| ${EVENT_TYPE} | Event type identifier (for example, user.created) |
| ${TIMESTAMP} | ISO 8601 timestamp |
| ${NEW_STATE} | JSON of entity after the event |
| ${OLD_STATE} | JSON of entity before the event (empty for creates) |
| ${ENTITY_ID} | Generic entity ID |
| ${ENTITY_TYPE} | Entity type (user, gateway, etc.) |

### Entity-specific variables

| Scope | Variables |
| User | ${USER_ID}, ${USERNAME}, ${USER_EMAIL}, ${USER_ROLE} |
| Gateway | ${GATEWAY_ID}, ${GATEWAY_NAME}, ${GATEWAY_DID}, ${GATEWAY_STATUS} |
| Connection Point | ${CP_ID}, ${CP_NAME}, ${CP_DID}, ${CP_STATUS}, ${GATEWAY_ID} |
| Channel | ${CHANNEL_ID}, ${CHANNEL_NAME}, ${CHANNEL_TYPE} |
| Identity | ${IDENTITY_ID}, ${IDENTITY_DID}, ${IDENTITY_TYPE} |

Custom variables can be defined with the _ prefix (for example, ${_MY_VAR}).