> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/integrations/integration-fundamentals/messaging-and-ticketing-integrations.md). # Messaging and Ticketing Integrations Integrate with any message or ticketing tool that's not listed in our native integrations with a custom message and ticket integration.
How do Material and message and ticketing integrations work together? Material can automatically create tickets in your ticketing system when specific events occur. Some common examples are: * New email threat issues detected * User-reported suspicious emails * High/critical severity issues * Custom detection triggers Material can also send notifications and alerts about any event so you can use that data in your management workflows.
### Available Messaging and Ticketing Integrations To set up an integration, you'll 1. Create an event destination in your third-party tool 2. Configure the integration in Material including adding triggering events Some messaging and ticketing tools have common events useful to that tool already added to get you started including: * Email * [Slack](#tool-specific-instructions) * [PagerDuty](#pagerduty-integration-key) * [Atlassian](https://support.atlassian.com/cloud-automation/docs/configure-the-incoming-webhook-trigger-in-atlassian-automation/) For all tools, [complete steps one and two below](#one-create-an-event-destination-in-the-third-party-tool). You can edit the preconfigured events as needed.
{% hint style="info" %} **Don't see your tool?** Use a custom message and ticketing integration — if your tool accepts HTTPS JSON payloads, it works with Material. {% endhint %} ## How to create a custom Messaging and Ticketing integration {% hint style="warning" %} A Super Admin or Tenant Admin [role](/learn-more/administration/admin-roles.md) is required to create custom messaging and ticketing integrations. {% endhint %} {% hint style="success" %} Looking to send alerts to email? [Learn more here](/integrations/integration-fundamentals/messaging-and-ticketing-integrations/email-notifications.md). {% endhint %} ### One: Create an event destination in the third-party tool Custom message and ticketing integrations are achieved via webhook. In the message/ticketing tool's webhook or connector interface: 1. Create and secure a webhook endpoint handler to receive event data requests (most often `POST`). Refer to your tool's documentation for instructions on how to do this. 2. Copy the endpoint URI and any required headers for use in the next section. ### Two: Configure the Message and Ticketing integration in Material 1. In Material, click **Integrations** (the puzzle icon in the top tool bar). 2. Click **Create New Integration** 3. Under **Messaging & Ticketing**, click **Custom Message and Ticketing**. Complete the required fields:
{% tabs %} {% tab title="Method" %} This is most often `POST` , however refer to your tool's documentation for the required method for their destination. {% endtab %} {% tab title="URI" %} The full HTTPS destination or endpoint URL for your tool; check their documentation or support. Create a unique custom webhook for each endpoint you need to deliver to. {% endtab %} {% tab title="Headers" %} Include any required headers for your destination. Sometimes this includes an auth header with a password; check your destination's documentation to confirm. {% endtab %} {% tab title="Event" %} Choose the event(s) that will trigger your custom messaging and ticketing webhook. Use the form to build the trigger based on multiple filters. * The most common event used is `Issue Change` . It covers most needs. * Other common filters are: * **Severities**: trigger based on an issue severity change * **Detection**: trigger based on a specific detection * Choose the option to **Include events for messages being added / removed / interacted with in a phishing case** if you want to also trigger based on individual message level changes (rather than just issue level changes). *** * While you can include multiple events in one integration, you can only include one of each event type (i.e. one issue change, etc.) All the filters must match to trigger the event. If you need to trigger webhook using OR logic, create multiple integrations with different event parameters.
* Toggle events off/on at any time in the integration view. * Once your custom SIEM webhook starts firing, the last time an event triggered is included in the integration view, under **Events**:
{% endtab %} {% endtabs %} 4. Add as many events as desired. ( :white\_check\_mark: tip: you can clone events rather than filling out the form each time. Click the copy icon to the right of the event row):
5. Integrations are toggled on by default, so if you want to test it first, toggle the integration **Off**, then **save** the Integration. 6. Open an event, then click **Send Test Event** to test your connection. (You need to save the integration first to see this option). * All webhooks send payloads with the same fields in JSON format. Event Descriptions are in app; click the **API** icon in the toolbar then click **Events**. * Material verifies SSL certificates when delivering payloads. * Once you have saved the integration, you can click **Copy Test Event** to view an example payload.
Example Payload {% code overflow="wrap" %} ```json { "eventId": "abc123", "timestamp": "YYYY-MM-DDTHR:MIN:SEC", "orgId": "demo", "uDomainId": "google://C029fz6xs/", "requestor": { "system": true }, "tenant": null, "account": null, "group": null, "file": null, "message": { "uDomainId": "google://abc123", "messageId": "", "msgDate": "YYYY-MM-DDTHR:MIN:SEC", "msgSender": "demo@acme.com" }, "app": null, "type": "CREATE", "issue": { "entityType": "MESSAGE", "uDomainId": "google://abc123", "messageId": "", "msgDate": "YYYY-MM-DDTHR:MIN:SEC", "id": "abc123", "entityId": "MESSAGE:{\"messageId\":\"\",\"msgDate\":\"YYYY-MM-DDTHR:MIN:SEC\",\"uDomainId\":\"google://abc123/\"}", "detectionId": "phishing-attack-user-report", "detectionType": "PHISHING_EVENT_BASED", "categories": [ "EMAIL_SECURITY" ], "tactics": [], "severity": "03-MEDIUM", "status": "OPEN", "lastStateChangeTimestamp": "YYYY-MM-DDTHR:MIN:SEC", "lastOpenedTimestamp": "2YYYY-MM-DDTHR:MIN:SEC", "lastResolvedTimestamp": null, "snoozedUntilTimestamp": null, "ignoreReason": null, "resolveReason": null, "classification": "MALICIOUS", "analysis": [], "scopes": [ { "type": "count", "countType": "num_accounts", "countValue": 1 }, { "type": "count", "countType": "num_messages", "countValue": 1 }, { "type": "count", "countType": "num_links", "countValue": 0 }, { "type": "count", "countType": "num_attachments", "countValue": 0 } ], "associatedEntityIds": [ "ACCOUNT:{\"uAcctId\":\"google://abc123/\",\"uDomainId\":\"google://abc123/\"}", "MESSAGE:{\"messageId\":\"\",\"msgDate\":\"YYYY-MM-DDTHR:MIN:SEC\",\"uDomainId\":\"google://abc123/\"}" ], "numAccounts": 1, "numMessages": 1, "numAttachments": 0, "numLinks": 0, "fixes": [ { "type": "tag", "label": "Speedbump" }, { "type": "tag", "label": "Warning Banner" }, { "type": "tag", "label": "Spam" } ], "extra": { "caseId": "20260309_KrTmx0YJ" }, "caseId": "20260309_KrTmx0YJ", "comments": [], "ownerUAcctId": null, "createdAt": "YYYY-MM-DDTHR:MIN:SEC", "updatedAt": "YYYY-MM-DDTHR:MIN:SEC", "lastCheckedAt": "YYYY-MM-DDTHR:MIN:SEC", "entityDisplayLabel": null, "detectionName": "Message flagged by user", "nameSearchValue": "", "nameSearchValueUpdatedAt": null, "dedupKey": "20260309_KrTmx0YJ", "dedupTimestamp": "YYYY-MM-DDTHR:MIN:SEC", "isMock": false, "issueName": "Message flagged by user", "issueLink": "https://acme.com" }, "after": null, "before": null, "getMaterialBaseUrl": { "url": "https://acme.com" } } ``` {% endcode %}
You can view a test event to help you build a receiver for JSON events without having to send test events and log the payload. From the event, click **View Test Event** to open a window with the full JSON payload and copy it to your clipboard. You need to save your integration first for this option to appear. See step 6 above.

From an integration, open an event row to view a test event

*** ### Tool Specific Instructions
Slack Tokens **In Material:** 1. Click **Integrations** (the puzzle icon in the top tool bar). 2. Click **Create Integration.** 3. Click **Slack**. 4. Click **Create New Integration**.
**In Slack:** {% hint style="warning" %} Always review [Slack's documentation](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/?utm_source=chatgpt.com) for up to date instructions. {% endhint %} 1. Log in to the [Slack apps dashboard](https://api.slack.com/apps) and create a new app using a manifest. Our YAML manifest is available at `https://[your-material-instance]/api/radar/slack/app_config` 2. On the **Basic Information** page, set the **App icon** to (optional). 3. On the **Install App** page, install the app to your workspace. 4. On the **Install App** page, there should now be a **Bot User OAuth Token**. Paste this value in Material. Slack relevant, pre-configured events are enabled by default. Edit or add [events](#event) as needed. Use the [instructions above](#two-configure-the-message-and-ticketing-integration-in-material) to complete your integration.
PagerDuty Integration Key **In Material:** 1. click **Integrations** (the puzzle icon in the top tool bar). 2. Click **Create Integration.** 3. Click **PagerDuty**. 4. Click **Create New Integration**. ![](/files/rZzCVmCsZPS6LSOYhTAH) **In PagerDuty:** {% hint style="warning" %} Always review [PagerDuty's documentation](https://support.pagerduty.com/main/docs/services-and-integrations) for up to date instructions. {% endhint %} Connect Material to PagerDuty using a [service integration](https://support.pagerduty.com/main/docs/services-and-integrations). 1. Log in to your PagerDuty instance. 2. Navigate to the **Service Directory** (under the **Services** tab.) 3. You can create a new service or use an existing one. 4. In the service, click the **Integrations** tab. Click **Add another integration**. When it asks which integration you would like to connect, select **Events API V2**. 5. Once the integration has been created, expanding its card will reveal an **Integration Key**. Paste this key into Material. PagerDuty relevant, pre-configured events are enabled by default. Edit or add [events](#event) as needed. Use the [instructions above](#two-configure-the-message-and-ticketing-integration-in-material) to complete your integration.
### Disable an integration 1. From the **Integrations** page, open the integration. 2. On the top right, toggle **Off**. *** ## Event Delivery Behavior ### Monitoring and Latency * **Latency, retries, and time-outs** * For the best experience, your endpoint needs to be able to keep up with incoming webhook events. We automatically retry failed deliveries, but if an endpoint continues to fail, we may disable the associated events. We recommend checking your event subscriptions from time to time to ensure they remain active. * **Deduplication** * Payloads aren't always deduplicated. It's best practice to implement deduplication logic at your destination. ## Troubleshooting {% hint style="success" %} **Test your endpoint** We recommend you always test your webhook in Material using the [**Send Test Event**](#two-configure-the-webhook-in-material) button. {% endhint %} #### Common Errors | Error Code | Description | Solution | | ---------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | 400 | Bad Request | Confirm your payload fields are formatted correctly for your tool's requirements | | 401 | Unauthorized | Verify token | | 403 | Forbidden | Check your headers in the payload to confirm correct permissions and roles including bearer tokens | | 404 | Not found | Verify your endpoint URL | | 408 | Timeout | Double check your endpoint and tool requirements | | 502 | Bad Gateway | Verify your endpoint URL, any intermediate infrastructure such as a load balancer or proxy, and your webhook implementation. | | 504 | Timeout | Double check your endpoint and tool requirements | ### Troubleshooting workflow If you're experiencing issues with your custom SOAR integration, try this troubleshooting workflow: 1. **Check Event Subscription Status:** Look for error messages in Material indicating why events might be failing or if subscriptions have been auto-disabled. For example:
2. **Verify Connectivity:** Ensure your tool can receive test events and that Material is set up as an app or similar, if needed (i.e. Slack) 3. **Validate Permissions:** Ensure your Material account has proper permissions for event subscriptions (Super Admin or Tenant Admin). 4. **Check Integration Logs:** Look for specific error messages in both Material and your messaging and ticketing platform. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.material.security/integrations/integration-fundamentals/messaging-and-ticketing-integrations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.