Documentation
Go to Integrations

Microsoft Teams Integration

Overview

Connect Microsoft Teams channels to Ticket MATE to receive real-time notifications about Jira issues. This integration allows you to send event-based alerts (e.g., "Issue Created", "Status Changed") directly to specific Teams channels.

Prerequisites

  • Microsoft Teams: You must have a Microsoft Teams workspace and permission to configure connectors in a channel.
  • Ticket MATE Admin: You must be a workspace administrator in Ticket MATE to manage integrations.

Setup Guide

1. Create an Incoming Webhook in Teams

  1. Open Microsoft Teams and navigate to the channel where you want to receive notifications.
  2. Click the More options (•••) button next to the channel name and select Connectors.
  3. Search for Incoming Webhook and click Configure.
  4. Give the webhook a name (e.g., "Ticket MATE Notifications").
  5. (Optional) Upload a logo for the bot.
  6. Click Create.
  7. IMPORTANT: Copy the URL that appears. This is your unique webhook URL. You will need this in the next step.
  8. Click Done.

2. Connect to Ticket MATE

  1. Log in to Ticket MATE and go to Admin > Integrations.
  2. Locate the Microsoft Teams integration card and click Manage.
  3. In the Webhooks tab, click Add Webhook.
  4. Channel Name: Enter a descriptive name for the webhook (e.g., #engineering-alerts). This is for your reference in Ticket MATE.
  5. Webhook URL: Paste the URL you copied from Teams in the previous section.
  6. Enabled: Ensure the switch is turned on.
  7. Click Test Connection to send a sample message to Teams.
  8. If the test is successful, click Save.

3. Configure Subscriptions

Once the webhook is added, you need to tell Ticket MATE what events to send to it.

  1. Go to the Subscriptions tab on the Teams integration page.
  2. Click Add Subscription.
  3. Event Type: Select the event you want to listen for (e.g., Issue Created, Issue Updated).
  4. Webhook: Select the webhook (channel) you just configured.
  5. Filters: (Optional) Add criteria to limit notifications.
    • Project: Only send notifications for specific projects (e.g., DEMO).
    • Issue Type: Only send for specific types (e.g., Bug).
    • Status: Only send when issues enter specific statuses (e.g., Done).
    • Priority: Only send for critical issues.
  6. Click Save.

Your integration is now active! Events matching your criteria will be posted to the configured Teams channel.

Security Best Practices

[!WARNING] Webhook URLs are secrets!

  • Treat URLs like passwords: Anyone with the webhook URL can post messages to your Teams channel. Do not share them in public channels or commit them to source control.
  • Encryption: Ticket MATE encrypts webhook URLs at rest in the database.
  • Masking: The UI masks the URL to prevent "shoulder surfing". You cannot view the full URL after saving it.
  • Rotation: If you suspect a URL has been compromised, remove the connector in Teams and create a new one, then update Ticket MATE.

Troubleshooting

Webhook returns 404

  • The webhook configuration may have been removed from the Teams channel.
  • Check if the URL is correct.
  • Try creating a new Incoming Webhook in Teams and updating Ticket MATE.

Messages not delivering

  • Check the Delivery Log tab in Ticket MATE to see detailed error messages.
  • Verify that the Webhook is Enabled.
  • Verify that the Subscription is Enabled.
  • Ensure your subscription filters match the events actually happening in Jira.

Rate Limiting (429)

  • Microsoft Teams enforces rate limits on incoming webhooks.
  • Ticket MATE automatically handles retries with exponential backoff for rate-limited requests.
  • If you see frequent 429 errors, consider reducing the volume of notifications (e.g., by adding more specific filters).

Audit Logging

All administrative actions related to Teams integrations are logged for security and compliance.

  • Webhook Created/Updated/Deleted: Logs who made the change and when.
  • Subscription Created/Deleted: Track changes to notification routing.
  • Test Connection: Logs test attempts.

Access audit logs via the Security > Audit Log page.

Technical Implementation

Ticket MATE uses a decoupled, event-driven architecture for Teams notifications to ensure performance and reliability.

1. Event Transformation

Jira webhooks are received at /api/webhooks/jira. A transformer standardized the raw payload into a unified JiraEvent envelope.

2. Event Routing

The EventRouter performs a database lookup to find active subscriptions matching the event type and workspace. It then applies granular filters (project, issue type, etc.).

3. Asynchronous Delivery

Routed events are enqueued in the IntegrationDeliveryLog with a pending status. A background worker (TeamsDeliveryWorker) polls this queue every 5 seconds, decrypts the webhook URLs, and delivers the messages to Teams as Adaptive Cards.

4. Reliability Features

  • Encryption: Webhook URLs are encrypted using AES-256-GCM.
  • Retries: Temporary failures (5xx, 429) trigger an exponential backoff retry strategy.
  • Timeouts: Deliveries have a strict 8-second timeout.
  • Dead-Letter Queue: Permanently failing messages are moved to a dead_letter status for manual inspection.