Download the PHP package tkrnx/laravel-teams-notifier without Composer

Laravel Teams Notifier

A small Laravel package for sending structured, fail-safe notifications to a Microsoft Teams Workflow webhook. It builds compact Adaptive Cards, adds application and request metadata, redacts sensitive context, and keeps Teams outages from breaking the application that reported the event.

Features

• INFO, WARNING, and ERROR notifications through one simple API
• Microsoft Teams Workflow-compatible Adaptive Card payloads
• Automatic application name, environment, timestamp, request path, request ID, and authenticated user ID
• Recursive, case-insensitive redaction of sensitive context keys
• Safe rendering and truncation of strings, arrays, objects, exceptions, and debug traces
• A card text budget that keeps generated messages below Teams' 28 KB message limit
• Fail-safe HTTP delivery with a short timeout and conservative retry
• Optional Laravel queue delivery without serializing Throwable objects
• Facade and dependency-injection APIs
• Laravel package auto-discovery and publishable configuration

Requirements

• PHP 8.2 or newer
• Laravel 11 or Laravel 12
• A Microsoft Teams Workflow webhook URL

Installation

Install the package with Composer:

Laravel discovers the service provider and TeamsNotifier alias automatically. Publish the configuration if you need to customize it:

The explicit provider form is also supported:

Configuration

Add the Workflow URL and the settings appropriate for your application:

The published config/teams-notifier.php file also contains the sensitive-key list. Add application-specific secret field names there when needed.

If notification delivery is enabled without a webhook URL, the package logs one warning per resolved webhook client and returns safely. The webhook URL itself is never included in package log messages.

Microsoft Teams Workflow Setup

Microsoft currently supports creating incoming webhooks through the Workflows app or from a channel/chat workflow template. The shortest setup is:

1. In Teams, open the target channel or chat's More options, then select Workflows.
2. Choose the appropriate Send webhook alerts to a channel/chat template.
3. Authenticate the connection, choose the destination, and add the workflow.
4. Copy the generated HTTP POST URL into TEAMS_NOTIFIER_WEBHOOK_URL.
5. Send a test notification from the application.

You can also create a workflow from blank with the When a Teams webhook request is received trigger and a Post card in chat or channel action. Microsoft's Workflows webhook setup guide covers both paths. For operational continuity, add co-owners to production workflows because workflows are owned by users.

The package sends the documented type: message envelope with application/vnd.microsoft.card.adaptive attachments. Microsoft documents this payload and the 28 KB message limit in its Teams incoming webhook developer guide.

Treat the generated URL as a secret. Store it in environment or secret-management configuration; do not commit it.

Basic Usage

Import the package facade:

With Laravel's discovered alias, use TeamsNotifier; is also available.

INFO Notifications

WARNING Notifications

ERROR Notifications

Attach an exception when it adds useful diagnostic detail:

Delivery failures are caught and logged, so the notifier does not replace the original business exception.

Exception Notifications

The shortcut creates an ERROR notification and uses the exception's short class name as its default title:

Override the title when a business-specific name is clearer:

Dependency Injection

Use the contract when a service should not depend on the facade:

Context Data

Context can contain strings, integers, floats, booleans, null, arrays, enums, dates, stringable values, and objects. Keys such as reward_id are displayed as Reward ID. Arrays and objects are safely converted to compact JSON.

During HTTP requests, the package automatically includes:

• HTTP method and path, without query parameters or request body
• X-Request-ID, then X-Correlation-ID, when supplied
• One stable generated UUID for the request when neither header exists
• Authenticated user ID when it can be resolved safely

The request body, authorization headers, cookies, and other headers are not collected.

Security and Sensitive Data

Sensitive keys are matched case-insensitively and recursively. The defaults are:

For example, both password and a nested Access_Token become [REDACTED]. Normal context strings are bounded to 2,000 characters, exception messages are bounded to 4,000 characters, debug traces are bounded to 8,000 characters, collection size and depth are capped, and the builder applies a final card text budget.

Full traces can reveal internal paths or values. TEAMS_NOTIFIER_INCLUDE_DEBUG is therefore false by default. Never put secrets in titles or exception messages; key-based redaction applies to context data.

Queue Support

Set queued delivery in production when the main request should not wait for Teams:

Run a Laravel queue worker using your application's normal queue configuration:

The queued job receives only scalar/array notification data. Exceptions are normalized to class, message, file, line, and an optional bounded trace before dispatch; raw Throwable objects are never serialized. The job allows one attempt and does not create another Teams alert when Teams delivery fails.

Failure Behavior

HTTP requests use Laravel's HTTP client, the configured short timeout, and two total attempts separated by 200 milliseconds. Non-success responses and transport exceptions are logged as warnings with only safe metadata such as status code or exception class. They are not thrown into application code.

Disable all HTTP and queue activity at runtime with:

Testing

The HTTP transport works with Laravel's normal HTTP fake:

Run the package checks locally:

The suite uses Orchestra Testbench and covers the facade, service provider, all levels, exception helper, request context, recursive redaction, card structure, payload size, disabled mode, missing webhooks, HTTP failures, queue dispatch, and queued delivery.

License

Laravel Teams Notifier is open-sourced software licensed under the MIT license.