- Docs
- Administration
- Integrations
- Webhooks
Generic webhooks
A webhook sends a signed JSON request to your endpoint whenever a chosen event happens in the project. Use it for ServiceNow, PagerDuty, Opsgenie, Power Automate or your own service.
In short
On this page you can
- Send pipeline started, completed and failed events to any HTTP endpoint.
- Send an event when a task is created or a deploy is received.
- Add up to 10 custom headers, such as an Authorization header.
- Check the last 50 deliveries with status code, attempts and duration.
- Verify each request with the
X-Smartest-SignatureHMAC.
How to use it
- Click Add webhook, enter a Name and the Payload URL.
- Pick the Events, add headers if needed, and save.
- Copy the Signing secret now: it is shown only once.
- Click Send test and check “Test delivered (HTTP 200)”.
- Verify the signature in your receiver before trusting the body.
Add a webhook#
Open the page
Go to IntegrationsGeneric Webhook. Under Outgoing webhooks click Add webhook.
Fill the form
In New webhook enter a Name (up to 120 characters) and the Payload URL: an
http://orhttps://address. Internal network addresses are allowed. Keep Active on.Pick events and headers
Under Events tick what you need (Pipeline completed and Pipeline failed are preselected). Under Custom headers (optional) click Add header for each Header and Value, for example an
Authorizationtoken your endpoint expects. Click Save.Copy the secret
A dialog shows the Signing secret (it starts with
whsec_): “Copy this secret now. It won't be shown again.” Store it in your receiver’s secret store.Send a test
Click Send test on the row.
“Test delivered (HTTP 200).” Your endpoint received an event of type
TEST.
Events#
| Event (label) | event value | Sent when | Fields in data |
|---|---|---|---|
| Pipeline started | PIPELINE_STARTED | A pipeline run starts | pipelineName, pipelineId, status = STARTED |
| Pipeline completed | PIPELINE_COMPLETED | A run ends and every test case passed | pipelineName, pipelineId, status, totalTests, passedTests, failedTests, durationMs, passRate |
| Pipeline failed | PIPELINE_FAILED | A run ends with at least one test case failed or not run | pipelineName, pipelineId, status = FAILED, error |
| Test failed | TEST_FAILED | Can be selected; this version does not send it. Use Pipeline failed. | testName, testSuiteName, testLogId, error |
| Defect created | DEFECT_CREATED | A task is created | defectTitle, defectId, severity, assignee |
| Deploy received | DEPLOY_RECEIVED | A CI tells SmartestQA about a deploy (see Deployments & Repos) | deploymentId, service, environment, commitSha, previousSha, status, version, branch, buildUrl, actor |
Webhooks fire whether or not Slack or Teams are set up. passRate is a percentage with one decimal; see the formula.
The request#
Every delivery is an HTTP POST with a JSON body in UTF-8:
{
"event": "PIPELINE_COMPLETED",
"deliveryId": "6f1c2e9a-4b0d-4c55-9d3e-2a7b1f0c8e41",
"occurredAt": "2026-11-08T07:42:10.512Z",
"project": { "id": 42, "name": "Customer Portal" },
"data": {
"pipelineName": "Nightly regression",
"pipelineId": 318,
"status": "COMPLETED",
"totalTests": 48,
"passedTests": 48,
"failedTests": 0,
"durationMs": 1254000,
"passRate": 100.0
}
}| Header | Value |
|---|---|
Content-Type | application/json; charset=utf-8 |
User-Agent | SmartestQA-Webhook/1 |
X-Smartest-Event | The event, for example PIPELINE_FAILED |
X-Smartest-Delivery | A unique id; the same on every retry of one delivery |
X-Smartest-Signature | sha256= followed by the lowercase hex HMAC-SHA256 of the raw body, keyed with the signing secret |
| Your custom headers | Added as entered. They cannot replace the headers above, Host, Content-Length or Connection. |
Verify the signature#
Compute the HMAC over the raw request body, before any JSON parsing, and compare it with the header in constant time.
const crypto = require('crypto');
function isFromSmartest(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Use X-Smartest-Delivery to ignore a delivery you already processed: a retry carries the same id.
Delivery, retries and the log#
- Success is any 2xx answer. SmartestQA waits up to 5 seconds to connect and 10 seconds for the answer, and reads only the first 2 KB of it.
- Retries: after a network error, a 5xx, 408 or 429, it tries again after 1 s, 5 s and 30 s (up to 4 attempts). Other 4xx answers are final.
- Send test makes a single attempt and shows “Test delivered (HTTP code).” or “Test failed: error”.
- Deliveries opens Recent deliveries: the last 50 deliveries of that webhook, with Time, Event, Status, Attempts and Duration.
- Busy endpoints: each webhook has at most 2 deliveries in flight and 100 waiting. Beyond that, new deliveries are dropped, so a slow endpoint does not hold up others.
- Blocked addresses: link-local addresses (
169.254.x.x,fe80::) and cloud metadata addresses are refused. Private and loopback addresses are allowed for on-premises receivers.
Edit, regenerate, delete#
- Edit: change name, URL, events, headers or Active. Saved header values are shown as
••••••; leave them as they are to keep them. If you change the URL to another host, saved header values are dropped and must be entered again, so a token is never sent to a new server by mistake. - Regenerate secret: “The old secret stops working immediately. Continue?” The new secret is shown once.
- Delete: “name and its delivery log will be deleted.”
Starting pipelines from outside#
This page only sends. To start a pipeline when another system calls SmartestQA, create a webhook trigger in Schedule (Triggers). It gives you a URL and a token, and incoming JSON fields can be mapped to pipeline inputs. The page’s Open triggers button takes you there. To run a pipeline from a CI job and wait for the result, use CI/CD.
Limits#
| Item | Limit |
|---|---|
| Webhooks per project | 20 |
| Custom headers per webhook | 10 (names: letters, digits and -, up to 64) |
| Name / URL length | 120 / 2,000 characters |
| Attempts per delivery | 4 |
| Deliveries kept per webhook | 50 |
If something goes wrong#
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai