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.
Scan a page when you deploy
Section titled “Scan a page when you deploy”1. Create a webhook token
Section titled “1. Create a webhook token”Owners and admins can create and revoke tokens.
- Open Settings → Notifications → Webhook tokens.
- Choose Create token, give it a name (for example Production deploy), and create it.
- 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.
2. Call the endpoint
Section titled “2. Call the endpoint”POST https://app.theaccessibility.company/api/webhooks/scanAuthorization: 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:
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.comandexample.comare 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):trueskips 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.
Responses
Section titled “Responses”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_REQUIREDorURL_MISMATCH: nourl, or it isn’t on the host of thesite_idyou gave. - 401
INVALID_TOKEN,TOKEN_NOT_FOUNDorTOKEN_REVOKED: the token is malformed, unknown or revoked. - 402
SUBSCRIPTION_REQUIRED: the workspace has no active plan. - 403 or 415: the
Content-Typeheader is missing or isn’tapplication/json. - 404
SITE_NOT_FOUND: no site in the workspace on that host, or thesite_idisn’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’sscan_run_id, when present, names the running scan. Try again once it finishes. - 429
RATE_LIMITEDorDAILY_SCAN_QUOTA_EXCEEDED: too many calls, or the site’s daily page limit is used. TheRetry-Afterheader says how many seconds to wait. - 500
SCAN_TRIGGER_FAILED: the scan couldn’t start for another reason. Try again in a minute.
Limits
Section titled “Limits”| 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.
Page checks
Section titled “Page checks”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.
Example: GitHub Actions
Section titled “Example: GitHub Actions”- 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.
Revoking a token
Section titled “Revoking a token”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.
Scan alerts
Section titled “Scan alerts”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.
Add a channel
Section titled “Add a channel”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. |
| 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.
Add rules
Section titled “Add rules”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.
Other emails
Section titled “Other emails”- 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.