> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimension.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Integration Patterns

> Webhook and Email patterns for common services

Actions in Dimension come in two forms — **Webhooks** and **Emails** — but the destinations you'll point them at follow predictable patterns. Here are the integration patterns we see most often.

## Webhook patterns

> [tab] Slack
>
> **Step 1** — In Slack, create an Incoming Webhook for the channel you want messages to land in.
>
> **Step 2** — In Dimension, create a Webhook Action and tell the Composer:
>
> ```text theme={null}
> "Create a webhook action that posts to Slack.
>  The URL is https://hooks.slack.com/services/T00/B00/xxx.
>  The payload format should be Slack Block Kit."
> ```
>
> Composer will scaffold a Block Kit payload that you can refine with prompts like:
>
> ```text theme={null}
> "Add a button to the message that opens the device's
>  detail page in our portal."
> ```

> [tab] Microsoft Teams
>
> Microsoft Teams Incoming Webhooks use a different payload shape (Adaptive Cards).
>
> ```text theme={null}
> "Create a webhook action that posts to Microsoft Teams
>  using an Adaptive Card. URL: <your-teams-webhook-url>."
> ```
>
> Composer handles the Card schema. Reference fields with `{device.name}`-style variables.

> [tab] Jira
>
> Jira REST API for creating issues:
>
> ```text theme={null}
> "Create a webhook action that creates a Jira issue.
>  URL: https://yourorg.atlassian.net/rest/api/2/issue.
>  Auth: Basic with the API token below.
>  Project key: SEC. Issue type: Bug."
> ```
>
> Composer will prompt for the API token securely (it won't be visible in the chat history).

> [tab] ServiceNow
>
> ServiceNow Table API for creating incidents:
>
> ```text theme={null}
> "Create a webhook action that POSTs to the ServiceNow
>  Incident table.
>  URL: https://yourorg.service-now.com/api/now/table/incident.
>  Auth: OAuth2 with refresh token."
> ```

> [tab] PagerDuty
>
> PagerDuty Events API v2 for paging on-call:
>
> ```text theme={null}
> "Create a webhook action that triggers a PagerDuty incident
>  via Events API v2.
>  Routing key: <your-routing-key>.
>  Severity should map from the device's risk level."
> ```

> [tab] Custom internal API
>
> Any HTTPS endpoint inside your network that you can reach from Dimension.
>
> ```text theme={null}
> "Create a webhook action that POSTs to
>  https://soar.internal.example.com/incidents.
>  Auth: Bearer token. JSON body."
> ```
>
> For self-hosted endpoints, see [Architecture](https://docs.dimension.io/trust/architecture.md) for source IPs and network requirements.

## Email patterns

> [!WARNING]
>
> **Email Action recipients are tenant-user-only.** The Recipients field on an Email Action is an autocomplete of users in your ThreatAware tenant — you cannot send to arbitrary email addresses or distribution lists. If you need to email external parties (customers, partners, auditors), wire a **Webhook Action** to an email API (SendGrid, Postmark, AWS SES) instead.

> [tab] Notify a single tenant user
>
> ```text theme={null}
> "Create an email action that emails the on-call security analyst.
>  Recipients: alice@yourorg.com (a tenant user).
>  Subject: 'Critical risk detected — {device.name}'.
>  Body: include the failing controls and a link to the device."
> ```

> [tab] Notify the device owner (if a tenant user)
>
> Works only when device owners are themselves ThreatAware tenant users — typical for internal IT teams managing employee assets.
>
> ```text theme={null}
> "Create an email action that emails {device.owner.email}.
>  Subject: 'Action required: {device.name}'.
>  Body: explain what they need to do, with a link to the device."
> ```
>
> If the owner is **not** a tenant user, switch to a Webhook Action against your transactional email provider (SendGrid, Postmark, AWS SES).

> [tab] Internal digest to a security DL
>
> A digest delivered to multiple tenant users — pick the actual user records from the Recipients picker:
>
> ```text theme={null}
> "Create an email action for weekly digests.
>  Recipients: jane@yourorg.com, joe@yourorg.com, ciso@yourorg.com
>  (all tenant users).
>  Subject: 'Weekly Security Summary'.
>  Body: structured HTML with metrics, top risks, top
>  compliance issues."
> ```
>
> Combine with auto-refresh in a Studio app to fire weekly.

> [tab] External recipients via Webhook
>
> To email someone who isn't a ThreatAware user:
>
> ```text theme={null}
> "Create a webhook action that sends an email via SendGrid.
>  URL: https://api.sendgrid.com/v3/mail/send.
>  Auth: Bearer token (SendGrid API key).
>  Body: SendGrid v3 JSON with {{input.to}}, {{input.subject}},
>  {{input.body}} interpolation."
> ```
>
> Same approach works for Postmark, AWS SES, Mailgun, or any other email API.

## Configuration tips

> [accordion] Don't put secrets in the prompt
>
> Composer prompts for secrets (API keys, OAuth client secrets) separately. They aren't stored in the Composer chat history.

> [accordion] Use variables for everything dynamic
>
> `{device.name}`, `{user.email}`, `{trigger.timestamp}`, `{app.name}`, etc. — Composer recognises these and wires them up.

> [accordion] Test against a sandbox first
>
> For webhooks, [requestbin.com](https://requestbin.com) lets you inspect payloads before pointing the Action at production.

> [accordion] Audit log catches platform changes
>
> Configuration changes show up in **Settings → Logs → Audit Log**. Outbound requests show up in **Settings → Logs → Request History**.

## See also

> [card] [Actions Overview](https://docs.dimension.io/actions.md)
>
> Creating a Webhook or Email Action from scratch

> [card] [Triggers & Invocation](https://docs.dimension.io/actions/triggers.md)
>
> The three invocation patterns Studio apps use


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.