Integrations reference
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. |
| Integration Name | string | Yes | Display name for the integration. |
| Description | string | No | Optional description. |
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 | Yes | SMTP authentication username. |
| Password | string | Yes | 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. |
| Email Format | string | Yes | HTML or Plain Text. |
| Body | string | Yes | Email body. Supports HTML and 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. |
| 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. Pre-filled with a randomly generated UUID. Replace with your own value if preferred. When set, the gateway sends an X-Webhook-Signature-256: sha256=<hex> header and an X-Webhook-Timestamp header with each delivery. |
| Custom Headers | string | No | Additional HTTP headers as a JSON map. |
| Payload Template | string | Yes | JSON payload template. Supports runtime variables. |
Stream
Stream events to enterprise messaging platforms.
Common stream fields:
| Field | Type | Required | Description |
|---|---|---|---|
| Streaming Platform | string | Yes | Apache Kafka, AWS Kinesis, Apache Pulsar, or Redis Streams. |
| 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. |
Kafka and Pulsar additional fields:
| Field | Type | Required | Description |
|---|---|---|---|
| Broker URLs | string | Yes | Comma-separated broker addresses. |
| Authentication Type | string | No | None or SASL/PLAIN. |
| 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 is populated from the gateway’s own configuration (the integration.categories list, returned to the dashboard by GET /v1/integrations/config), not a fixed set built into the dashboard itself. The options an operator actually sees can differ from one deployment to another.
The table below lists the categories defined in Affinidi’s shipped example gateway configuration, as a typical, illustrative set rather than a guaranteed one.
| Category | Events triggered |
|---|---|
| General | Not tied to one entity type. Matches general-purpose notifications rather than a specific entity’s lifecycle events. |
| Connection Point | connection_point.created, connection_point.updated, connection_point.deleted, connection_point.connected, connection_point.error |
| 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 |
| Channel | channel.created, channel.updated, channel.deleted, channel.accessed, channel.error |
| Identity | identity.created, identity.updated, identity.deleted, identity.appeared, identity.accessed |
A deployment that hasn’t set its own category list falls back to a built-in default, which keeps the first five categories above but replaces Identity with an x402 category for payment events. Between this and the config-driven nature of the list, check your own deployment’s Integrations page for the categories actually on offer rather than assuming this table is exhaustive.
Runtime variables
Use ${VARIABLE} syntax in any field marked “Supports runtime variables” above (subjects, message bodies, and payload templates). Variables are resolved when the event fires. General variables are available to every integration; each other category below adds its own variables on top of the general set, scoped to that category’s events. Custom variables can be defined with an underscore prefix, for example ${_MY_VAR}.
General
Available to every integration, regardless of category.
| Variable | Description |
|---|---|
${OLD_STATE} | JSON representation of the entity’s state before the event. Empty for create events. |
${NEW_STATE} | JSON representation of the entity’s state after the event. Empty for delete events. |
${EVENT_TYPE} | The event that triggered the integration, for example gateway.created. |
${TIMESTAMP} | ISO 8601 timestamp of when the event occurred. |
${SERVER_NAME} | Name of the gateway server. |
${SERVER_DOMAIN} | Domain name of the server. |
${MESSAGE_ID} | Unique identifier for the message or event. |
Connection Point
Available when the integration’s category is Connection Point.
| Variable | Description |
|---|---|
${CP_ID} | Unique identifier of the connection point. |
${CP_NAME} | Display name of the connection point. |
${CP_DESCRIPTION} | Description of the connection point. |
${GATEWAY} | Name of the associated gateway. |
${GATEWAY_ID} | Unique identifier of the associated gateway. |
User
Available when the integration’s category is User.
| Variable | Description |
|---|---|
${USER_ID} | Unique identifier of the user. |
${USERNAME} | Username of the user. |
${USER_EMAIL} | Email address of the user. |
${USER_ROLE} | Role assigned to the user (Administrator, Power User, or User). |
${USER_STATUS} | Current status of the user (New, Approved, or Disabled). |
Gateway
Available when the integration’s category is Gateway.
| Variable | Description |
|---|---|
${GATEWAY_ID} | Unique identifier of the gateway. |
${GATEWAY_NAME} | Display name of the gateway. |
${GATEWAY_DESCRIPTION} | Description of the gateway. |
${GATEWAY_DID} | Decentralized Identifier (DID) of the gateway. |
${GATEWAY_TYPE} | Type of gateway. |
${GATEWAY_STATUS} | Current status of the gateway. |
${GATEWAY_OLD_STATUS} | Previous status of the gateway. Only populated on status-change events. |
Channel
Available when the integration’s category is Channel.
| Variable | Description |
|---|---|
${CHANNEL_ID} | Unique identifier of the channel. |
${CHANNEL_NAME} | Display name of the channel. |
${CHANNEL_PROTOCOL} | Protocol type, for example a2a or mcp. |
Identity
Available when the integration’s category is Identity.
| Variable | Description |
|---|---|
${IDENTITY_DID} | Decentralized Identifier (DID) of the identity. |
${IDENTITY_TYPE} | Type of DID, for example did:web or did:key. |
${IDENTITY_CONTROLLER} | DID of the identity’s controller. |
${CHANNEL_ID} | Channel where the identity appeared. Only populated on appearance events. |
Further categories
The gateway also defines runtime variables for four further categories, MCP Proxy, Mediator, Trust Registry, and Secrets, none of which appear in the category lists shown above. If your deployment’s configuration defines an integration category with a matching name, these variables become available the same way the categories above do.
| Category | Variables |
|---|---|
| MCP Proxy | ${MCP_PROXY_ID}, ${MCP_PROXY_NAME}, ${MCP_PROXY_DESCRIPTION}, ${MCP_PROXY_TARGET_URL}, ${MCP_PROXY_STATUS} |
| Mediator | ${MEDIATOR_ID}, ${MEDIATOR_NAME}, ${MEDIATOR_DESCRIPTION}, ${MEDIATOR_ENDPOINT}, ${MEDIATOR_DID}, ${MEDIATOR_STATUS} |
| Trust Registry | ${TRUST_REGISTRY_ID}, ${TRUST_REGISTRY_NAME}, ${TRUST_REGISTRY_DESCRIPTION}, ${TRUST_REGISTRY_DID}, ${TRUST_REGISTRY_STATUS} |
| Secrets | ${SECRET_ID}, ${SECRET_NAME}, ${SECRET_DESCRIPTION}, ${SECRET_TAGS} |
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.