
Each local area page used to take us half a day to create and optimize.
With SEOmatic, we can create hundreds of pages in the same time, which helps our clients make the best use of their budget.
It's transformed how we deliver scalable SEO solutions.
Will Hawkins
Marketing Director, Digi-Business UK
Agents read your Search Console data, do the work, and prove what actually moved. You decide what ships.
14-Day Trial for $1, credited to your first payment.
Register HTTPS endpoints that receive a signed POST the moment something happens in your workspace. Available on the Infrastructure plan.
Register and manage endpoints in the dashboard or over the REST API, with a key that has the chat:ask scope on a workspace on the Infrastructure plan. A workspace can have up to 25 endpoints. Each call is a full endpoint in the REST reference:
GET /v1/webhooks list your endpoints
POST /v1/webhooks register one (secret returned once)
PATCH /v1/webhooks/{id} enable/disable, change events
POST /v1/webhooks/{id}/rotate-secret new secret; the old one keeps signing for 24h
DELETE /v1/webhooks/{id} remove oneSubscribe to all events (default) or a subset. Rotating the secret returns the new one once, with the time the old one stops signing:
{
"id": "<webhook id>",
"secret": "whsec_...",
"previousSecretValidUntil": "2026-09-25T12:00:00.000Z"
}X-Seomatic-Delivery id.PATCH /v1/webhooks/{id} with {"enabled": true} turns it back on and clears the failure count.410 Gone to unsubscribe: the endpoint is deleted and not retried.Every delivery is a POST with these headers:
| Header | Meaning |
|---|---|
X-Seomatic-Event | The event name, e.g. page.published. |
X-Seomatic-Signature | t=<unix>,v1=<hmac-sha256 hex> over `${timestamp}.${body}`. |
X-Seomatic-Timestamp | Unix seconds the delivery was signed. Reject if stale. |
X-Seomatic-Delivery | The delivery id. It stays the same across retries of one event, so use it to skip an event you already processed. |
User-Agent | SEOmatic-Webhooks/1 |
Recompute the HMAC-SHA256 over `${timestamp}.${body}` with your endpoint's signing secret, constant-time compare it to X-Seomatic-Signature, and reject a stale X-Seomatic-Timestamp to defeat replay:
import crypto from "node:crypto";
// secret = the whsec_... shown once at endpoint creation. Verify the RAW
// bytes, never re-serialized JSON: in Express, mount the route with
// express.raw({ type: "application/json" }) so req.body is the exact Buffer.
//
// app.post("/hooks/seomatic", express.raw({ type: "application/json" }),
// (req, res) => {
// if (!verify(req, process.env.SEOMATIC_WHSEC)) return res.sendStatus(400);
// const event = JSON.parse(req.body.toString("utf8"));
// res.sendStatus(200); // answer 2xx within 10 seconds
// });
export function verify(req, secret, toleranceSec = 300) {
// "t=...,v1=..." - during a secret rotation there is one v1 per active
// secret ("t=...,v1=<new>,v1=<old>"): accept the event if ANY v1 matches.
const sig = req.headers["x-seomatic-signature"];
const ts = Number(req.headers["x-seomatic-timestamp"]);
const body = req.body.toString("utf8"); // the EXACT bytes received
// 1) Reject a stale timestamp (replay guard).
if (!ts || Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
// 2) Recompute HMAC-SHA256 over `${ts}.${body}` and constant-time compare.
const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${body}`)
.digest("hex");
const candidates = [...(sig || "").matchAll(/v1=([a-f0-9]+)/g)].map(m => m[1]);
return candidates.some(
got =>
got.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
);
}
// Rotating the secret: POST /api/v1/webhooks/{id}/rotate-secret returns the
// new whsec_... once. For 24 hours every delivery is signed with BOTH secrets,
// so deploy the new one any time in that window without dropping events.
// Rotating again inside the window replaces the older secret immediately.import hashlib, hmac, re, time
def verify(headers, raw_body: bytes, secret: str, tolerance_sec: int = 300) -> bool:
sig = headers.get("X-Seomatic-Signature", "")
try:
ts = int(headers.get("X-Seomatic-Timestamp", ""))
except ValueError:
return False
# 1) Reject a stale timestamp (replay guard).
if abs(time.time() - ts) > tolerance_sec:
return False
# 2) Recompute HMAC-SHA256 over f"{ts}.{body}" and constant-time compare.
# During a rotation there is one v1 per active secret: accept ANY match.
expected = hmac.new(
secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
).hexdigest()
return any(
hmac.compare_digest(got, expected)
for got in re.findall(r"v1=([a-f0-9]+)", sig)
)
# Flask: verify(request.headers, request.get_data(), os.environ["SEOMATIC_WHSEC"])Every delivery shares one envelope: event, workspace_id, created_at, a data object whose fields depend on the event (documented below), event_id (evt_…, the same on every retry, so use it to skip an event you already processed) and cursor (the event's place in the workspace's event log, as a string; null in the rare case the log write failed).
A page went live on the customer's site.
| Field | Type | Description |
|---|---|---|
data.page_id | string (uuid) | |
data.project_id | string (uuid) | |
data.url | string | the live URL |
data.cms_item_id | string | id in the customer's CMS (the file path on a GitHub site) |
data.published_at | string (ISO 8601) |
{
"event": "page.published",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"page_id": "b1e2…",
"project_id": "a9c0…",
"url": "https://acme.com/compare/x-vs-y",
"cms_item_id": "1042",
"published_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}A page failed to publish.
| Field | Type | Description |
|---|---|---|
data.page_id | string (uuid) | |
data.project_id | string (uuid) | |
data.error | string | failure reason (truncated) |
data.failed_at | string (ISO 8601) |
{
"event": "page.publish_failed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"page_id": "b1e2…",
"project_id": "a9c0…",
"error": "CMS returned 401 (auth expired)",
"failed_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}An SEO agent task finished executing. Not sent for a run that settled as advice or an index request with nothing written to the site.
| Field | Type | Description |
|---|---|---|
data.task_id | string (uuid) | |
data.type | string | e.g. ctr_fix, alt_text |
data.target | string | the page/entity it acted on |
data.applied | boolean | the run wrote a change to the site |
data.live | boolean | the change was already seen on the live page; false until task.live fires |
{
"event": "task.completed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"task_id": "77b4…",
"type": "ctr_fix",
"target": "https://acme.com/pricing",
"applied": true,
"live": false
},
"event_id": "evt_…",
"cursor": "18342"
}The agent staged work that needs a human decision. Only for a task that would run once approved (not while, say, no site is connected or credits are used up). One event per task, at most 10 per staging batch: the approval board in the app always holds the full list. Pair with the REST decide_seo_task tool (or the Zapier Decide SEO Task action) to approve or dismiss from wherever the event lands.
| Field | Type | Description |
|---|---|---|
data.task_id | string (uuid) | |
data.type | string | null | e.g. content_create, ctr_fix |
data.title | string | null | the goal, in plain words |
data.target | string | null | page URL or topic |
data.approve_in_app | string (url) |
{
"event": "task.awaiting_approval",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"task_id": "77b4…",
"type": "content_create",
"title": "Cover a topic your audience searches for",
"target": "programmatic seo guide",
"approve_in_app": "https://app.seomatic.ai/dashboard/agents"
},
"event_id": "evt_…",
"cursor": "18342"
}A person approved or dismissed a task: from the dashboard, an email link, Slack, an agency client's approval link, an assistant, MCP or the REST API. Once per decided task. Automatic approvals do not fire it.
| Field | Type | Description |
|---|---|---|
data.task_id | string (uuid) | |
data.type | string | null | e.g. ctr_fix, alt_text |
data.title | string | null | what the task does |
data.target | string | null | page URL or topic |
data.decision | "approve" | "dismiss" | |
data.decided_by | "user" | "client" | "slack" | "email" | "mcp" | "api" | "assistant" | where the decision was made: the dashboard (user), an agency client link, Slack, an email link, MCP, the REST API, or an assistant acting on the person's word |
data.decided_at | string (ISO 8601) |
{
"event": "task.decided",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"task_id": "77b4…",
"type": "ctr_fix",
"title": "Sharper title for the pricing page",
"target": "https://acme.com/pricing",
"decision": "approve",
"decided_by": "slack",
"decided_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}A change SEOmatic made was seen on the live page, so its effect is now measured against its own baseline. Once per task. Not sent for old changes found live by a backfill.
| Field | Type | Description |
|---|---|---|
data.task_id | string (uuid) | |
data.type | string | e.g. ctr_fix, alt_text |
data.title | string | what the change did |
data.target | string | the page or query it targeted |
data.url | string | null | the page where the change was seen, when recorded |
data.live | boolean | always true |
data.verified_at | string (ISO 8601) |
{
"event": "task.live",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"task_id": "77b4…",
"type": "ctr_fix",
"title": "Sharper title for the pricing page",
"target": "https://acme.com/pricing",
"url": "https://acme.com/pricing",
"live": true,
"verified_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}A change SEOmatic made was undone and the page shows what it had before: a person's undo (one change, a whole campaign, or undo-all), or the automatic revert when the change clearly hurt the page (clicks fell, or real users' page speed got worse). Once per undone change.
| Field | Type | Description |
|---|---|---|
data.task_id | string (uuid) | |
data.type | string | null | e.g. ctr_fix, alt_text |
data.title | string | null | what the change did |
data.target | string | null | the page or query it targeted |
data.campaign_id | string (uuid) | null | its campaign, when it was part of one |
data.rolled_back_by | "human" | "auto" | null | a person undid it, or the automatic revert; null when not recorded |
data.rolled_back_at | string (ISO 8601) |
{
"event": "task.rolled_back",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"task_id": "77b4…",
"type": "ctr_fix",
"title": "Sharper title for the pricing page",
"target": "https://acme.com/pricing",
"campaign_id": null,
"rolled_back_by": "auto",
"rolled_back_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}Every Monday: the workspace's weekly report, with the changes settled this week, changes seen live or not, fixes waiting for approval and the top wins. Fires every week for workspaces with the SEO agents or an AI visibility monitor on (paying or on a carded trial), also when the weekly email and Slack report are turned off.
| Field | Type | Description |
|---|---|---|
data.domain | string | null | the site's Search Console property |
data.window_from | string | first day counted (YYYY-MM-DD) |
data.window_to | string | last day counted (YYYY-MM-DD) |
data.verified | integer | changes that won this week |
data.ineffective | integer | changes that settled with no clear effect |
data.regressed | integer | changes that settled worse |
data.reverted | integer | changes undone this week |
data.live | integer | changes seen on the live page this week |
data.not_live | integer | changes not seen live after every check |
data.awaiting_approval | integer | fixes waiting for a person |
data.wins | object[] | the top wins of the week: { title, lift_pct } (lift_pct is null when not stored) |
data.report_url | string (url) | where to read it in the app |
{
"event": "weekly_report.ready",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"domain": "sc-domain:acme.com",
"window_from": "2026-08-21",
"window_to": "2026-08-27",
"verified": 3,
"ineffective": 1,
"regressed": 0,
"reverted": 1,
"live": 6,
"not_live": 0,
"awaiting_approval": 2,
"wins": [
{
"title": "Sharper title for the pricing page",
"lift_pct": 18.5
}
],
"report_url": "https://app.seomatic.ai/dashboard"
},
"event_id": "evt_…",
"cursor": "18342"
}A campaign finished with at least one change seen on the live page. Once per campaign. Not sent for a campaign that ended with nothing live (every task dismissed or failed, advice only, or written but not showing on the page).
| Field | Type | Description |
|---|---|---|
data.campaign_id | string (uuid) | |
data.type | string | topic_cluster, refresh_sweep, ctr_sweep, technical_pass, internal_link_architecture, single_fix, page_scale, location_pages, content_sweep or bulk_edit |
data.tasks_total | integer | |
data.tasks_succeeded | integer | |
data.tasks_live | integer | tasks whose change was seen on the live page |
data.completed_at | string (ISO 8601) |
{
"event": "campaign.completed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"campaign_id": "c3d4…",
"type": "page_scale",
"tasks_total": 120,
"tasks_succeeded": 118,
"tasks_live": 118,
"completed_at": "2026-08-28T12:00:00.000Z"
},
"event_id": "evt_…",
"cursor": "18342"
}An AI-visibility scan finished, whether you started it or it ran on its schedule.
| Field | Type | Description |
|---|---|---|
data.scan_id | string (uuid) | |
data.brand | string | the brand name the scan looked for |
data.per_engine | object[] | one entry per engine: engineId, label, promptsChecked, mentions, visibility (mentions / promptsChecked, 0 to 1), competitors [{ name, count }], sources [{ url, count }]; when measured also ghostCitations (answers that cited your domain without naming you), ci95 { low, high }, runsPerPrompt, partial (the engine answered under half the questions) and memoryOnly (answers from model memory, not scored) |
data.credits_charged | integer | |
data.lost_answers | object[] | up to 15 answers that mentioned you last scan and no longer do: { prompt, engineId, competitors }, where competitors are the names now in that answer |
data.gained_answers | object[] | up to 15 answers that mention you now and did not last scan, same shape |
{
"event": "ai_visibility.scan_completed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"scan_id": "e5f6…",
"brand": "Acme",
"per_engine": [
{
"engineId": "openai",
"label": "ChatGPT",
"promptsChecked": 10,
"mentions": 4,
"visibility": 0.4,
"competitors": [
{
"name": "Globex",
"count": 6
}
],
"sources": [
{
"url": "g2.com",
"count": 3
}
]
}
],
"credits_charged": 6667,
"lost_answers": [
{
"prompt": "best crm for small agencies",
"engineId": "openai",
"competitors": [
"Globex"
]
}
],
"gained_answers": []
},
"event_id": "evt_…",
"cursor": "18342"
}A search the site ranks for slipped. Two sources: the daily Search Console watch (workspaces with the SEO agents on; a query the site earns clicks on, last 2 complete weeks against the 4 before, once per query per week), and the Rank Tracker's daily checks (a tracked search that stayed the alert's number of places below its usual place for its hold days, 3 places for 2 days by default, or left the Google Maps top 3). Rank Tracker events add source, kind, city and device, and send 0 for the Search Console-only numbers.
| Field | Type | Description |
|---|---|---|
data.query | string | the search |
data.page | string | null | the site's page for that search, when known |
data.prior_position | number | the usual position before (for a Maps exit: the Maps position it held) |
data.recent_position | number | the position now; 21 means out of the top 20; 0 for a Maps exit |
data.positions_lost | number | 0 for a Maps exit |
data.recent_impressions | integer | Search Console only; 0 from the Rank Tracker |
data.recent_clicks | integer | Search Console only; 0 from the Rank Tracker |
data.click_share | number | share of the site's clicks this query carries, 0 to 1; 0 from the Rank Tracker |
data.passed_by | object | null | who passed it, when known: { domain, url, position } from Search Console, { domain, position } from the Rank Tracker |
data.defense_task_id | string (uuid) | null | the fix staged for approval, when there is one |
data.fleet_volatile | boolean | Google rankings were moving across many sites at the time; always false from the Rank Tracker |
data.window | string | what was compared, in words |
data.source | "rank_tracker" | Rank Tracker events only; absent from Search Console events |
data.kind | "drop" | "maps_exit" | Rank Tracker events only |
data.city | string | null | Rank Tracker events only; null = the country-level market |
data.device | "mobile" | "desktop" | Rank Tracker events only |
{
"event": "ranking.dropped",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"query": "water heater repair",
"page": "https://acme.com/water-heater-repair",
"prior_position": 3.2,
"recent_position": 7.8,
"positions_lost": 4.6,
"recent_impressions": 1840,
"recent_clicks": 62,
"click_share": 0.0812,
"passed_by": {
"domain": "globex.com",
"url": "https://globex.com/water-heaters",
"position": 2
},
"defense_task_id": "77b4…",
"fleet_volatile": false,
"window": "Search Console average position: the last 2 complete weeks vs the 4 before"
},
"event_id": "evt_…",
"cursor": "18342"
}Google now shows a different page of the site for a tracked search than the one that held it the 3 checks before: two of the site's pages compete for it. From the Rank Tracker's daily checks, once, the day it is seen.
| Field | Type | Description |
|---|---|---|
data.query | string | the tracked search |
data.city | string | null | null = the country-level market |
data.device | "mobile" | "desktop" | |
data.from_page | string | the page that held it |
data.to_page | string | the page Google shows now |
data.fix_task_id | string (uuid) | null | the fix staged for approval, when there is one |
data.day | string | the check day (YYYY-MM-DD) |
{
"event": "ranking.page_changed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"query": "water heater repair",
"city": "Georgetown, TX",
"device": "mobile",
"from_page": "https://acme.com/water-heater-repair",
"to_page": "https://acme.com/blog/water-heater-tips",
"fix_task_id": null,
"day": "2026-08-28"
},
"event_id": "evt_…",
"cursor": "18342"
}A new review arrived on a connected Google Business Profile listing, with the reply SEOmatic drafted in the brand voice. Needs a Google Business Profile listing picked in the app; checked daily.
| Field | Type | Description |
|---|---|---|
data.location | string | the Google listing id, e.g. "locations/456" |
data.business | string | the listing's name |
data.stars | integer | 1 to 5 |
data.reviewer | string | null | |
data.comment | string | null | the review text |
data.drafted_reply | string | null | null when no draft was made |
data.reply_task_id | string (uuid) | null | the approval task for the reply, when one was staged |
data.auto_send | boolean | the reply goes out without a person: only 4 and 5 stars, with auto-reply on, on a listing the owner picked, and a review not flagged; replies to 1 to 3 stars always wait for a person |
{
"event": "review.received",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"location": "locations/456",
"business": "Acme Plumbing",
"stars": 5,
"reviewer": "Dana R.",
"comment": "Fixed our water heater the same day.",
"drafted_reply": "Thanks, Dana! Glad we could get your hot water back fast.",
"reply_task_id": "77b4…",
"auto_send": false
},
"event_id": "evt_…",
"cursor": "18342"
}Every Monday: calls, direction requests and website clicks from the Google Business Profile over the last 7 days of data, with last week's calls for comparison. Needs a Google Business Profile listing picked in the app. Google's numbers run about 2 days behind.
| Field | Type | Description |
|---|---|---|
data.week_ending | string | the last day with data (YYYY-MM-DD) |
data.calls | integer | |
data.calls_week_before | integer | calls in the 7 days before |
data.direction_requests | integer | |
data.website_clicks | integer | |
data.note | string | where the numbers come from |
{
"event": "business_profile.calls_report",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"week_ending": "2026-08-26",
"calls": 41,
"calls_week_before": 35,
"direction_requests": 18,
"website_clicks": 77,
"note": "From Google Business Profile performance data (about 2 days behind)."
},
"event_id": "evt_…",
"cursor": "18342"
}On the workspace's update day, when no Business Profile update was drafted in the last 6 days. Once a week. Needs a connected Google Business Profile listing in good standing.
| Field | Type | Description |
|---|---|---|
data.message | string | what to do: send a job photo with one line about the job |
{
"event": "business_profile.update_due",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"message": "This week's Business Profile update has not been drafted yet. Send a job photo with one line about the job (app, Slack DM or business_profile_manage draft_update)."
},
"event_id": "evt_…",
"cursor": "18342"
}Another Google Maps listing looks like this business. Duplicates can get a profile suspended. A flag only: nothing is changed. Found by the weekly Business Profile checks (Mondays, or a Refresh in the app), once per new duplicate.
| Field | Type | Description |
|---|---|---|
data.location | string | the Google listing id, e.g. "locations/456" |
data.business | string | the listing's name |
data.duplicate_title | string | |
data.duplicate_address | string | null | |
data.advice | string | what to do about it |
{
"event": "business_profile.duplicate_found",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"location": "locations/456",
"business": "Acme Plumbing",
"duplicate_title": "Acme Plumbing Georgetown",
"duplicate_address": "12 Main St, Georgetown, TX",
"advice": "Possible duplicate listing. Duplicates can get a profile suspended. Nothing was changed: ask Google to remove or merge it from the Business Profile help center."
},
"event_id": "evt_…",
"cursor": "18342"
}A deep site audit finished, with how many issues are new or fixed since the previous audit. Not sent for a cancelled audit.
| Field | Type | Description |
|---|---|---|
data.run_id | string (uuid) | |
data.host | string | the site crawled |
data.score | integer | health score, 0 to 100 |
data.pages_crawled | integer | |
data.by_severity | object | issue counts: { error, warning, notice } |
data.new_issues | integer | null | issues not in the previous audit; null when there is no comparable earlier audit |
data.fixed_issues | integer | null | issues gone since the previous audit; null when there is no comparable earlier audit |
data.truncated | boolean | the crawl stopped at its page limit before covering the whole site |
{
"event": "site_audit.completed",
"workspace_id": "…",
"created_at": "2026-08-28T12:00:00.000Z",
"data": {
"run_id": "d7e8…",
"host": "acme.com",
"score": 86,
"pages_crawled": 412,
"by_severity": {
"error": 3,
"warning": 21,
"notice": 40
},
"new_issues": 4,
"fixed_issues": 9,
"truncated": false
},
"event_id": "evt_…",
"cursor": "18342"
}