testosaurusdocs
Browse docs
On this page

Webhooks & alerts

Testo playing tennis

Reports shouldn't live in a dashboard you forget to open. Point a project's webhook at your own endpoint, or at a small relay in front of the chat tool your team already uses, and every analyzed report pings you where the work happens.

Configure a webhook

In the dashboard, open settings → alerts for an app. The Webhook card takes a webhook URL. It has no field for the signing secret: Testosaurus generates the signing secret the first time you save a webhook URL, and shows it to you then so you can copy it into your receiver. generate a new secret replaces it, and the old one stops working immediately. A secret typed in earlier is still used as it is stored. The secret lets your receiver prove the request came from Testosaurus, and either kind is used as plain text exactly as it is stored. The Notifications card decides what is sent:

  • Send a webhook for new reports gates the submission.new event.
  • Send a webhook when analysis fails gates the submission.distill_failed event.
  • Email me about critical and high issues gates the email alert described below.

Both webhook switches stay off until a webhook URL is saved.

Delivery

  • Method: JSON POST with content-type: application/json.
  • When: after the report has been analyzed, or once its analysis ends without a result: skipped (AI paused, or out of credit), no usable answer, or failed for good. The alert email and automatic coding runs go first, so a slow endpoint never delays them.
  • At most once: each report is delivered once, with a 10 second timeout and no retries. Re-analyzing, merging or splitting issues never sends submission.new again, and a failed delivery is not repeated. Make your receiver answer quickly with a 2xx status.
  • Signature: every delivery carries an x-testosaurus-signature header, described under Verify the signature.

submission.new

Sent once for every report, when its analysis ends. Reports about the same problem are grouped into an issue, so issue_id tells you which issue a report belongs to, and distilled is the shared summary of that issue. It is null when analysis was skipped or failed. Using Re-analyze later never sends another submission.new for the report.

json
{
  "event": "submission.new",
  "id": "4f0c2d9e-7a31-4b8e-9c55-1d2e3f4a5b6c",
  "issue_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "distilled": {
    "title": "Checkout button does nothing on Safari",
    "category": "bug",
    "severity": "high",
    "summary": "Tapping Pay does nothing in Safari; works in Chrome.",
    "suggested_cause": "The click handler uses an API Safari does not support.",
    "steps": ["Open /checkout in Safari", "Tap Pay"],
    "provider": "openai/gpt-4o-mini"
  },
  "ts": "2026-10-10T09:30:00.000Z"
}

When analysis was skipped or failed, the same envelope arrives with distilled set to null:

json
{
  "event": "submission.new",
  "id": "4f0c2d9e-7a31-4b8e-9c55-1d2e3f4a5b6c",
  "issue_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "distilled": null,
  "ts": "2026-10-10T09:30:00.000Z"
}

Testosaurus writes event, id, issue_id and ts. Every field inside distilled is derived from what site visitors typed, so treat it as untrusted input: escape it before you show it in a page or a chat message, and never run it as a command. The fields of distilled:

  • title, summary: short text.
  • category: bug, confusing, idea or other.
  • severity: low, medium, high or critical.
  • steps: a list of steps to reproduce, possibly empty.
  • suggested_cause and provider (the model that answered): present only when known.

submission.distill_failed

Sent when the analysis of a report fails for good: after its automatic retries (three attempts over about 20 minutes), when it is abandoned in the dead-letter queue, or when the AI answer cannot be used. A Re-analyze that fails the same way sends it too. A report that fails for good also gets a submission.new with distilled set to null if it has not been announced yet. The event never carries error text. Open the report in the dashboard and use Re-analyze to try again. A Re-analyze that cannot even be queued is shown in the dashboard only. issue_id is null when the report failed before it was grouped into an issue.

json
{
  "event": "submission.distill_failed",
  "id": "4f0c2d9e-7a31-4b8e-9c55-1d2e3f4a5b6c",
  "issue_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "ts": "2026-10-10T09:31:00.000Z"
}

webhook.test

A test delivery carries no report. It is a POST with the same content-type, the same x-testosaurus-signature header and the same 10 second timeout as every other delivery, so your receiver can check its signature code against it before a real report arrives. id is a fresh random identifier and ts the time it was sent.

json
{
  "event": "webhook.test",
  "id": "0b6f1c52-3d1e-4f55-8a9b-7c2d4e6f8a10",
  "ts": "2026-10-10T09:32:00.000Z"
}

The workspace owner sends one with send test on the Webhook card. You can send up to five tests per app in each fixed 10-minute window; past that, the card says how many seconds to wait. A redirect is reported but not followed, and a test with no answer within the 10 second timeout counts as failed. The card shows the status and how long the answer took, or why the delivery failed.

Answer it with a 2xx status like any delivery. It never contains issue_id or distilled, so code that reads those fields should check event first.

Verify the signature

The signature is the lowercase hex HMAC-SHA256 of the exact raw request body, keyed with your project's signing secret used as plain text, exactly as it was typed or generated. There is no prefix and no timestamp. Compute it over the raw bytes before parsing the JSON, because re-serializing the body changes the bytes. Compare in constant time:

js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromTestosaurus(rawBody, signature, secret) {
  const expected = Buffer.from(createHmac('sha256', secret).update(rawBody).digest('hex'));
  const received = Buffer.from(signature ?? '');
  return expected.length === received.length && timingSafeEqual(expected, received);
}

High-severity email alerts

For reports rated high or critical, Testosaurus sends an email alert to the workspace owner's account address. It arrives once per issue: re-analyzing, merging or splitting does not repeat it, and it is sent again only when a re-analysis raises the severity above the earlier one. Team members do not receive it. Switch it per project with Email me about critical and high issues in the Notifications card on settings → alerts. Lower severities stay in the dashboard and the webhook.

Chat tools and trackers

  • Slack, Discord and similar tools expect their own message format and do not accept this payload directly. Put a small relay in front: a serverless function or an automation service that verifies the signature, then posts a message built from distilled.title and a link to the dashboard.
  • GitHub and Linear need no webhook. Connect them under settings → integrations; each project picks its repository or team under Send issues to, and you raise issues from the dashboard.
  • Your own pipeline: verify the signature first, then filter, dedupe by issue_id and forward.
Something unclear?Let us know