Skip to content

Webhooks and alerts

Webhooks run in two directions:

  • Incoming: your deploy step calls a webhook and we scan a page, so a release is checked minutes after it ships.
  • Outgoing: when a scan finishes, fails or finds new problems, an alert goes to Slack, Google Chat or an email address.

Both are on every plan.

Owners and admins can create and revoke tokens.

  1. Open Settings → Notifications → Webhook tokens.
  2. Choose Create token, give it a name (for example Production deploy), and create it.
  3. Copy the token. It starts with whtk_ and is shown once; we keep only a hash of it.

Store it as a secret in your CI or hosting platform. One token can scan any site in the workspace, so a name per pipeline makes it clear which to revoke if one leaks.

POST https://app.theaccessibility.company/api/webhooks/scan
Authorization: Bearer <token>

Send the token in the Authorization header. A token in the URL is refused (410): URLs are kept in logs. Send a JSON body with the page to scan:

Terminal window
curl -X POST "https://app.theaccessibility.company/api/webhooks/scan" \
-H "Authorization: Bearer $TAC_WEBHOOK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.example.com/pricing"}'

The Content-Type: application/json header is required: without it the request is refused.

  • url (required): the page to scan. Its host picks the site: the site in your workspace with exactly that host (the oldest, if two share one). www.example.com and example.com are different hosts.
  • site_id (optional): scan for this site instead of matching by host. The URL must still be on the site’s host.
  • notify_only_on_regression (optional): true skips the “scan completed” alert for this scan, so you only hear about it when it finds new problems.
  • event (optional): an object you choose to store with the scan, for example {"source": "github-actions", "commit": "4f2a9c1"}.

Each call scans one page, with the site’s settings: its rules, its signed-in scanning credentials, and its interaction scenarios. To check several pages after a deploy, call it once per page (mind the limits below). Results appear in the site’s scan history like any other scan, and any alerts you have set up go out when it finishes.

A new scan returns 202 Accepted:

{
"scan_run_id": "run_9x8y7",
"scan_target_id": "tgt_1a2b3",
"status": "running",
"dispatch_status": "enqueued",
"site_id": "site_a1b2c",
"deduped": false
}

The same token and URL again within the same minute returns 200 with the first scan’s scan_run_id and "deduped": true, so a pipeline that retries does not scan twice. To read the result later, use the REST API’s list scans endpoint with the site_id.

Errors come back as JSON with a code:

  • 400 URL_REQUIRED or URL_MISMATCH: no url, or it isn’t on the host of the site_id you gave.
  • 401 INVALID_TOKEN, TOKEN_NOT_FOUND or TOKEN_REVOKED: the token is malformed, unknown or revoked.
  • 402 SUBSCRIPTION_REQUIRED: the workspace has no active plan.
  • 403 or 415: the Content-Type header is missing or isn’t application/json.
  • 404 SITE_NOT_FOUND: no site in the workspace on that host, or the site_id isn’t yours.
  • 409 SCAN_IN_PROGRESS: another scan of the same site is running, and one scan per site runs at a time. The body’s scan_run_id, when present, names the running scan. Try again once it finishes.
  • 429 RATE_LIMITED or DAILY_SCAN_QUOTA_EXCEEDED: too many calls, or the site’s daily page limit is used. The Retry-After header says how many seconds to wait.
  • 500 SCAN_TRIGGER_FAILED: the scan couldn’t start for another reason. Try again in a minute.
Limit Value
Calls per token 20 a minute
Calls per workspace, across all tokens 60 a minute
Calls per IP address 60 a minute
Scans per site 10 a minute
Single-page scans per site per day Starter 25, Growth 100, Pro 250, Enterprise 1,000
Scans running per site 1

The daily single-page limit is shared with Scan a single page on the site’s overview: webhook and manual single-page scans draw on the same count.

A webhook scan is an on-demand page check: each page it scans counts toward your plan’s monthly fair-use allowance (22,500 on Starter, 90,000 on Growth, 300,000 on Pro, custom on Enterprise). Scheduled scans and fix-verification scans never count. Owners get an email at 80% of the allowance and again when it is passed; checks past it are not blocked but are billed as overage on the next invoice. Settings → Usage shows the month’s count.

- name: Scan the pricing page
if: github.ref == 'refs/heads/main'
run: |
curl --fail-with-body -X POST \
"https://app.theaccessibility.company/api/webhooks/scan" \
-H "Authorization: Bearer ${{ secrets.TAC_WEBHOOK_TOKEN }}" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.example.com/pricing", "event": {"source": "github-actions", "ref": "${{ github.ref_name }}", "commit": "${{ github.sha }}"}}'

Run it after the deploy step has finished, so the scan sees the new release.

In Settings → Notifications → Webhook tokens, open the token’s menu and choose Revoke token. Calls with it fail with 401 at once. Revoking cannot be undone; create a new token for the pipeline.

Alerts go to channels, and rules decide which events reach which channel. Owners and admins manage them in Settings → Notifications → Channels & rules; everyone else sees them read-only.

Under Notification channels, choose Add Channel, name it, and pick a type:

Type What you need
Slack Webhook An incoming webhook URL from your Slack workspace.
Google Chat Webhook An incoming webhook URL from a Google Chat space.
Email An email address.

Webhook URLs and email addresses are stored encrypted. Choose Test channel from a channel’s menu to check it arrives.

There is no general-purpose outgoing webhook: Slack and Google Chat channels send messages in that app’s own format.

A new channel is subscribed to Scan Completed straight away. For the other events, choose Add Subscription under Notification rules:

Event Sent when
Scan Completed A scan finishes. Scans called with notify_only_on_regression skip it.
Regression Detected A scan finds problems the previous comparable scan did not have.
Scan Failed A scan could not complete.

Each rule can be limited to one Site and to a Minimum Impact, so a channel only hears about scans with problems at or above that impact. Delivery history on the same page lists recent attempts and any errors.

  • Weekly digest. Owners get a Monday morning summary of the workspace’s week: new and resolved issues, scan activity, the top open issues, and for each site what its review has done with the change since last week. Quiet weeks are skipped. Owners and admins can turn it off in Settings → Notifications → Channels & rules, where anyone else in the workspace can opt in to their own copy.
  • Issue emails. Assignments, mentions, comments on issues you watch and status changes on issues assigned to you. Each person can mute these in Settings → Preferences.
  • Billing and usage. Owners hear when page checks reach 80% of the allowance and when they pass it, when a plan change makes scheduled scans less frequent, and when a lapsed subscription pauses them.

For issue trackers and pull requests, see Jira sync, Linear sync and GitHub.