---
title: "Webhooks"
section: "Integrations"
description: "Set up SmartestQA outgoing webhooks: events, payload JSON, the X-Smartest-Signature HMAC-SHA256 header, custom headers, retries, delivery log and limits."
url: https://docs.smartestqa.ai/en/integrations-webhooks.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "webhook outgoing signed json hmac sha256 x-smartest-signature x-smartest-event x-smartest-delivery signing secret whsec retries deliveries servicenow pagerduty opsgenie power automate payload"
---
# Integrations: 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-Signature HMAC.

**How to use it**

1. Click Add webhook , enter a Name and the Payload URL .
2. Pick the Events , add headers if needed, and save.
3. Copy the Signing secret now: it is shown only once.
4. Click Send test and check “Test delivered (HTTP 200)”.
5. Verify the signature in your receiver before trusting the body.

## Add a webhook

1. **Open the page**

   Go to **Integrations** › **Generic Webhook**. Under **Outgoing webhooks** click **Add webhook**.
2. **Fill the form**

   In **New webhook** enter a **Name** (up to 120 characters) and the **Payload URL**: an `http://` or `https://` address. Internal network addresses are allowed. Keep **Active** on.
3. **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 `Authorization` token your endpoint expects. Click **Save**.
4. **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.
5. **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](https://docs.smartestqa.ai/en/schedule-create.html) 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](https://docs.smartestqa.ai/en/deployments.html)**) | `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](https://docs.smartestqa.ai/en/integrations-numbers.html#webhook-passrate).

## The request

Every delivery is an HTTP `POST` with a JSON body in UTF-8:

Example · PIPELINE_COMPLETED

```json
{
  "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.

Node.js receiver

```javascript
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**](https://docs.smartestqa.ai/en/report-summary.html#test-cases-table) 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](https://docs.smartestqa.ai/en/schedule-create.html) 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](https://docs.smartestqa.ai/en/integrations-cicd.html).

## 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

- [“URL must be a valid http(s) address”](https://docs.smartestqa.ai/en/integrations-troubleshooting.html#fix-wh-url)
- [“Test failed: …”](https://docs.smartestqa.ai/en/integrations-troubleshooting.html#fix-wh-test-failed)
- [My receiver rejects the signature](https://docs.smartestqa.ai/en/integrations-troubleshooting.html#fix-wh-signature)
- [“A project can have at most 20 webhooks.”](https://docs.smartestqa.ai/en/integrations-troubleshooting.html#fix-wh-limit)
