⚠️ Proposed functionality – feedback requested!
The automation linking feature described on this page is proposed functionality for an upcoming Testmo release and is not yet generally available.
Testmo webhooks send real-time notifications to external tools whenever key events occur in your testing workflow. Use webhooks to post test run results to Slack, notify Microsoft Teams when a milestone completes, trigger Jenkins builds after a test run fails, or send structured JSON to any tool that accepts an HTTP POST request. This article explains how webhooks work, the events you can subscribe to, and how to create and manage webhook subscriptions.
Plan requirement
Outgoing webhooks are available on the Business and Enterprise plans. If your plan is downgraded, all active webhook subscriptions are automatically deactivated and preserved — they are not deleted — so you can reactivate them individually after upgrading again.
How webhooks work
When a subscribed event occurs in Testmo, the system places a delivery job in a background queue. The job sends an HTTP POST request to your configured URL, carrying a JSON payload that describes the event. This happens asynchronously — Testmo does not wait for a response before completing the action that triggered the event.
Each payload is signed with an HMAC-SHA256 signature so your receiving system can verify that the request genuinely came from Testmo. If a delivery fails, Testmo retries automatically up to three times before marking it as permanently failed.
Supported webhook types
Testmo provides first-class integrations for the most common communication and automation platforms, automatically formatting notifications to render correctly without additional configuration. Use a Generic webhook to connect any tool that accepts an HTTP POST.
- Using Webhooks with Slack Delivers payloads formatted as Slack Block Kit messages with rich cards, project names, test counts, and direct links back to Testmo. Uses Slack Incoming Webhook URLs.
- Using Webhooks with Microsoft Teams Delivers payloads as Adaptive Cards to your Teams channel. Requires a Workflows (Power Automate) webhook URL the older Office 365 Connector format is being retired by Microsoft.
- Using Webhooks with Discord Delivers payloads as Discord embed messages with color-coded sidebars, structured fields, and timestamps.
- Using Webhooks with Jenkins Triggers Jenkins builds automatically using the Generic Webhook Trigger plugin when test runs complete or automation fails.
- Using Webhooks with Other Tools Delivers a structured Generic JSON payload to GitHub, GitLab, Jira, custom dashboards, or any endpoint that accepts an HTTP POST. Includes payload structure reference and signature verification code examples.
Available events
You can subscribe a webhook to any combination of the following events. A webhook fires only for the events you have explicitly selected.
Test Runs
| Event | When it fires |
|---|---|
| Test run created | A new test run is created |
| Test run started | A test run transitions to an in-progress state |
| Test run completed | A test run completes (passed or failed) |
| Test run deleted | A test run is permanently deleted |
Test Cases
| Event | When it fires |
|---|---|
| Test case created | A new test case is added to a repository |
| Test case updated | A test case's name, steps, or fields are changed |
| Test case automation links changed | A test case's automation links are added, removed, or modified (requires automation linking to be enabled) |
| Test case state changed | A test case is archived or reactivated |
| Test case deleted | A test case is permanently deleted from a repository |
Automation Runs
| Event | When it fires |
|---|---|
| Automation run created | A new automation run is submitted to Testmo (via CLI or API) |
| Automation run completed | An automation run finishes (passed or failed) |
| Automation run deleted | An automation run is deleted |
CI/CD Jobs
| Event | When it fires |
|---|---|
| Job queued | A CI/CD job is triggered from Testmo (e.g., a Jenkins build or GitHub Actions workflow) |
| Job completed | A Testmo-initiated CI/CD job finishes execution (success or failure) |
Milestones
| Event | When it fires |
|---|---|
| Milestone created | A new milestone is created in a project |
| Milestone updated | A milestone's name, description, or custom fields are changed |
| Milestone due date changed | A milestone's due date is changed or cleared |
| Milestone completed | A milestone is marked as completed |
Test Sessions
| Event | When it fires |
|---|---|
| Test session created | A new exploratory test session is opened |
| Test session closed | An exploratory test session is marked as closed |
Test Results & Issues
| Event | When it fires |
|---|---|
| Test result changed | A test result is logged for a case within a run (pass/fail/skip) |
| Result issue linked | An issue (bug/defect) is linked to a test result |
Mentions
| Event | When it fires |
|---|---|
| User mentioned | A team member is @mentioned in a comment or note within Testmo |
Project scope and the User mentioned event
For mention events, Testmo resolves the project context from the entity where the mention occurred — for example, the project that owns the run or test case being commented on. A project-scoped webhook fires only when this resolved project matches the webhook's configured project scope.
Creating webhooks
Webhooks can be configured to fire for events across all projects (system-wide) or only for specific projects (project-scoped).
- System-wide webhooks fire for matching events in any project in your Testmo instance. Only system administrators can create and manage them via Admin > Webhooks.
- Project-scoped webhooks fire only for matching events in selected projects. System administrators can create project-scoped webhooks for any projects; project administrators can create them for their own projects via Project Settings > Webhooks.
To create a webhook:
- Navigate to Admin > Webhooks (system administrators) or Project Settings > Webhooks (project administrators).
- Click Add webhook.
- In the WEBHOOK tab:
- Enter a name for the webhook — this is for your reference only and does not affect delivery.
- Enter the Target URL. The URL must use HTTPS for Slack, Teams, and Discord webhooks.
- Select a webhook type — Slack, Microsoft Teams, Discord, or Generic.
- Select one or more events that should trigger this webhook. You must select at least one event to save.
- In the PROJECTS tab:
- Select This webhook applies to all projects to create a system-wide webhook (system administrators only).
- Or select This webhook applies to the following projects only and choose which projects should trigger this webhook.
- Click Save. Testmo generates a signing secret and displays it once with a Copy to clipboard button — copy it immediately and store it securely. It cannot be retrieved after you leave this screen.
URL requirements
Slack, Microsoft Teams, and Discord webhook URLs must use HTTPS. For Generic webhooks, plain HTTP and self-signed TLS certificates are also supported by enabling the Allow insecure connections toggle an amber warning is shown before you save. Addresses that resolve to private or internal networks are always rejected at save time to prevent server-side request forgery.
Managing webhooks
Activating and deactivating
Each webhook has an Active or Inactive status. When set to Inactive, Testmo pauses all deliveries for that subscription without deleting it or its delivery history. Use deactivation to pause a webhook during maintenance or troubleshooting, then reactivate it when you are ready to resume deliveries.
Editing webhooks
Open a webhook from the list to edit its configuration. You can update the target URL, change the selected events, modify the webhook type, or adjust project scope. The signing secret cannot be viewed after creation, but you can regenerate it at any time using the Regenerate secret action & update your receiving application at the same time, as deliveries signed with the old secret will fail verification.
Deleting webhooks
Deleting a webhook removes the subscription and cancels all future deliveries. Historical delivery records are retained for the configured retention period for audit purposes.
Delivery history retention
System administrators can configure how long delivery history records are kept. Navigate to Admin > Webhooks and use the Delete webhook delivery history after dropdown at the top of the page.
| Option | Behaviour |
|---|---|
| After 7 days | Delivery records older than 7 days are permanently deleted |
| After 30 days | Delivery records older than 30 days are permanently deleted |
| After 90 days (default) | Delivery records older than 90 days are permanently deleted |
This setting applies globally to all webhook subscriptions. Delivery records are permanently deleted, not archived when they exceed the configured retention period.
Verifying payloads with signing secrets
Every webhook subscription has a signing secret — a cryptographic key Testmo uses to sign each outgoing payload. Use this secret in your receiving application to confirm that a request genuinely came from Testmo and has not been modified in transit.
Testmo includes the signature in the X-Testmo-Signature-256 HTTP header of every delivery, as an HMAC-SHA256 hash of the raw request body computed using the subscription's signing secret. In your receiving application, compute the same HMAC and compare it using a constant-time string comparison to avoid timing attacks.
- The signing secret is shown only once — immediately after you create the webhook. Use the Copy to clipboard button and store it securely, for example as an environment variable in your receiving application.
- If you lose the secret, use Regenerate secret on the webhook. Update your receiving application at the same time — deliveries signed with the old secret will fail verification.
Signature verification examples
See Using Webhooks with Other Tools for Node.js and Python code examples for verifying the X-Testmo-Signature-256 header.
Sending a test payload
Use the Send test payload action to dispatch a sample event to your webhook URL immediately, without waiting for a real event to occur in Testmo. This is useful for confirming that your endpoint is reachable and that your receiving application parses the payload correctly.
- Open the webhook from the webhooks list.
- Click Send test payload. Testmo dispatches a sample payload for the first selected event type.
- Open the Delivery history tab to confirm the test delivery was received. Test deliveries are labelled Test to distinguish them from real event deliveries.
Test payloads work on inactive webhooks
You can send a test payload even when the webhook status is Inactive, making it straightforward to verify a new webhook before enabling it in production.
Viewing and managing delivery history
Every delivery attempt — including retries and test payloads — is recorded in the Delivery history tab for each webhook. Each entry shows the timestamp, event type, HTTP response code, delivery duration, attempt number, and final status (Delivered, Failed, or Pending). Click any entry to view the full payload that was sent and the full response received from your endpoint — Copy to clipboard buttons are available for the request payload, response body, and any error messages, making it easy to share diagnostic information with your team.
What "Delivered" means
A Delivered status means Testmo received an HTTP 2xx response from your endpoint — it does not indicate that the receiving system processed or acted on the event.
Filtering and retrying deliveries
Use the status filter at the top of the delivery history view to show only delivered, failed, or pending deliveries.
If a delivery has reached the maximum number of retry attempts and is marked as permanently failed, a Retry button appears on that entry. Click it to dispatch a new delivery attempt immediately.
Testmo retries failed deliveries automatically on the following schedule before marking them as permanently failed:
- Immediately after the initial failure
- 2 minutes after the first retry
- 10 minutes after the second retry
HTTP 4xx responses are not retried
HTTP 4xx responses — other than 429 Too Many Requests — are treated as permanent failures immediately. A 4xx response means the receiving server explicitly rejected the payload, so retrying is unlikely to succeed. HTTP 429 and all 5xx responses follow the retry schedule above.
Bulk operations
System administrators can perform bulk operations on delivery history from the Admin > Webhooks page:
- Clear webhook delivery history — Permanently delete all delivery records across all webhook subscriptions. This action requires confirmation and cannot be undone.
- Download delivery history — Export all delivery records in JSON format, including request payloads, response bodies, headers, and metadata. Useful for compliance, auditing, or analysing delivery patterns.
Managing webhooks via the REST API
All webhook management actions available in the UI — creating, updating, deleting, and querying delivery history — are also available via the Testmo REST API. This is useful for teams managing Testmo configuration as code, provisioning webhooks from CI pipelines, or building tooling that automates webhook setup. The API enforces the same plan requirement and URL validation rules as the UI. The signing secret is returned only in the response to the create request — subsequent reads return it masked.
Webhooks API reference
See the Webhooks API for endpoint details, request parameters, authentication, and example responses.
Frequently asked questions
Q: Can I send the same event to multiple destinations?
A: Yes — create a separate webhook subscription for each target URL. You can have multiple active subscriptions for the same event type, and each delivers independently. There is no restriction on duplicate URL or event combinations.
Q: What happens if my endpoint is temporarily unavailable?
A: Testmo retries automatically — immediately after the failure, then after 2 minutes, then after 10 minutes. If all three attempts fail, the delivery is marked as permanently failed. Use the Retry button in the delivery history to trigger a fresh attempt at any time.
Q: Can I use an HTTP URL instead of HTTPS?
A: For Slack, Microsoft Teams, and Discord webhooks, no — their endpoints are always HTTPS-only. For Generic webhooks, HTTP and self-signed TLS certificates are supported by enabling Allow insecure connections in the webhook form. Use HTTPS wherever possible; reserve this option for tools such as Jenkins that commonly operate without a valid TLS certificate.
Q: How do I verify that a payload came from Testmo?
A: Compute an HMAC-SHA256 hash of the raw request body using your subscription's signing secret, and compare it — using a constant-time comparison — against the value in the X-Testmo-Signature-256 header. See Using Webhooks with Other Tools for code examples.
Q: What happens to webhooks if my plan is downgraded?
A: All active webhook subscriptions are automatically deactivated and no further deliveries are sent. Your subscriptions are preserved — not deleted — so you can review and selectively reactivate them after upgrading again. Subscriptions are not automatically reactivated on upgrade; each one must be reactivated manually.
Q: Can individual users create their own webhooks?
A: No. Webhooks are managed by project administrators (for project-scoped webhooks) and system administrators (for system-wide and project-scoped webhooks). Regular users do not have access to webhook settings.
Q: How does the User mentioned event scope to a project?
A: When a user is @mentioned in a comment or note, Testmo resolves the project context from the entity containing that comment — for example, the project that owns the test run or test case. A project-scoped webhook fires only when that resolved project matches the webhook's configured project scope. System-wide webhooks fire for all mentions regardless of project.
Q: What happens to a project-scoped webhook when the project is deleted?
A: The webhook subscription is deactivated and its delivery history entries are marked as orphaned, making it clear in the history that the associated project no longer exists.
Q: Is there a limit on how many webhooks I can create?
A: There is no hard limit. Testmo is designed to support up to 1,000 active subscriptions per instance without affecting the performance of core functionality.
Q: Can I configure a webhook to fire for multiple projects but not all projects?
A: Yes. When creating or editing a webhook, select This webhook applies to the following projects only in the PROJECTS tab and choose which projects from the list. The webhook fires only for events in the selected projects.