Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
docs(content): document Send to CMS and the content_draft.sent webhook (Send to CMS #1331, part 4) (#1441)
Cihan6933f6c762d5
diff --git a/docs/api-reference/webhooks.mdx b/docs/api-reference/webhooks.mdxindex 4d9d6c7b6..b4ac026b4 100644--- a/docs/api-reference/webhooks.mdx+++ b/docs/api-reference/webhooks.mdx@@ -1,6 +1,6 @@---title: "Webhooks"-description: "Outbound webhooks for content opportunities and the Daily Pulse."+description: "Outbound webhooks for content opportunities, Content Editor pages and the Daily Pulse."---## Configuration@@ -11,7 +11,7 @@ Each brand has one webhook, set up in **Content → Configure Webhook**:- **Secret key** (optional) — sent back to you in a header on every request, so your endpoint can tell that the call came from Ansvisor.- **Active** — pause delivery without deleting the webhook.-Choose the events a webhook should receive in **Content → Configure Webhook**. Migration 00198 keeps existing webhooks subscribed to all three supported events until a user saves a new selection. **Test Webhook** always sends `webhook.test`, regardless of the saved selection.+Choose the events a webhook should receive in **Content → Configure Webhook**. Migration 00198 keeps existing webhooks subscribed to the three events it knew until a user saves a new selection. `content_draft.sent` (00262) is opt-in: tick **Content page sent** to receive pages. **Test Webhook** always sends `webhook.test`, regardless of the saved selection.## Events@@ -20,6 +20,7 @@ Choose the events a webhook should receive in **Content → Configure Webhook**.| `opportunity.sent` | A user sends a content opportunity to the workflow — from the opportunity page, or several at once from the opportunities list || `daily_pulse.created` | A brand's Daily Pulse is generated (on cloud and self-host alike) || `action_task.sent` | A user sends an Action Center task to the configured webhook |+| `content_draft.sent` | An admin or manager sends a Content Editor page to the CMS: from the editor, a Library row, or up to 25 selected Library pages ([Send to CMS](/guides/send-to-cms)) || `webhook.test` | **Test Webhook** is pressed in the webhook settings (always sent, independent of subscriptions) |## Verifying requests@@ -45,6 +46,26 @@ function isFromAnsvisor(req, secret) {The secret travels in the request itself, so only use an `https://` endpoint.+### Signature (`content_draft.sent`)++`content_draft.sent` requests also carry a signature of the raw request body, made with the same secret:++```+X-Ansvisor-Signature: sha256=<hex HMAC-SHA256 of the body>+```++Compute it over the body exactly as received, before parsing it, and compare in constant time:++```js+import crypto from 'crypto';++function isSignedByAnsvisor(rawBody, signature, secret) {+ const expected = `sha256=${crypto.createHmac('sha256', secret).update(rawBody).digest('hex')}`;+ const received = Buffer.from(signature ?? '');+ return received.length === expected.length && crypto.timingSafeEqual(received, Buffer.from(expected));+}+```+## Event payloadsPayloads are flat JSON objects with an `event` field at the top level.@@ -184,6 +205,72 @@ Every highlight and warning also has a `key` that identifies its subject.}```+### `content_draft.sent`++One request per page:++```json+{+ "event": "content_draft.sent",+ "schemaVersion": 1,+ "delivery": {+ "id": "uuid",+ "batchId": "uuid",+ "sentAt": "2026-10-24T10:00:00.000Z"+ },+ "page": {+ "draftId": "uuid",+ "title": "How to brew pour-over coffee",+ "slug": "pour-over-coffee",+ "metaTitle": "Pour-over coffee: a step-by-step guide",+ "metaDescription": "Pour slowly in circles for an even extraction.",+ "html": "<p>Pour slowly in circles for an even extraction.</p>…",+ "jsonLd": [{ "@context": "https://schema.org", "@type": "HowTo", "name": "How to brew pour-over coffee" }],+ "author": "Ada Lovelace",+ "featuredImage": { "src": "https://cdn.example.com/cup.jpg", "alt": "A cup of pour-over coffee" },+ "method": "optimize",+ "sourceUrl": "https://www.acme.example/blog/pour-over-coffee",+ "pageType": "guide",+ "language": "en"+ },+ "brand": { "id": "uuid", "name": "Acme", "domain": "acme.example", "industry": "Food & Beverage" },+ "callback_url": "https://api.example.com/webhooks/content-drafts/<delivery id>/status",+ "callback_method": "POST"+}+```++- `schemaVersion` is the package's format, `1` today.+- `delivery.batchId` is shared by the pages sent in one request of several pages (a bulk send); it is `null` for a page sent on its own.+- `page.html` is the page ready to publish, as **Export** gives it: placeholders filled, without its H1 (the title field carries it), with the brand's byline line when it adds the byline to its content. Ansvisor cleans it once more before sending: no scripts except JSON-LD, no frames, forms or event handlers, and links only to `http`, `https`, `mailto`, `tel` or relative addresses (images may also be `data:image/…`).+- `page.jsonLd` is the page's JSON-LD, each block parsed, or `[]`. Many CMS rich-text fields drop `<script>` from `page.html`, so add these to the post's head or its schema field.+- `page.metaTitle` is the title when none was set. `page.author` is the page's author or the brand's team byline, or `null`. `page.featuredImage` is the page's first `https` image, or `null`.+- `page.method` is `create` for a new page and `optimize` for one made from a live page, whose address is `page.sourceUrl` (otherwise `null`): update that post rather than creating another. `page.pageType` is the page's type in the editor (`blog_post`, `guide`, `comparison`…), or `null`.+- `page.language` is a two-letter code: the page's **Language** rule when it is on (the workspace's **My rules** for a page whose rules no one has changed), otherwise the brand's language, otherwise `en`.+- `callback_url` and `callback_method` are `null` when the webhook has no secret key.++#### Report how it went++When the page is live, send its address to `callback_url`:++```bash+curl -X POST "<callback_url>" \+ -H "Content-Type: application/json" \+ -H "X-Webhook-Secret: <your secret key>" \+ -d '{ "status": "published", "url": "https://www.example.com/blog/pour-over-coffee", "externalId": "812" }'+```++If your CMS refused the post, say so instead:++```json+{ "status": "failed", "reason": "The slug is already taken" }+```++- The `X-Webhook-Secret` must be the secret of an active webhook of the brand that receives `content_draft.sent`. An unknown delivery, a missing webhook and a wrong secret all answer 401.+- `status` is `published` or `failed`. `published` needs `url`: an `http` or `https` address without sign-in details, up to 2,048 characters as a browser reads it. `externalId` (optional) is your CMS's id for the post, as text up to 200 characters or a whole number, and `reason` (optional, up to 500 characters) says why it failed. A field sent empty or as `null` counts as left out. Anything else answers 400.+- `published` marks the send **published** with that address. When it is the page's latest send, the draft becomes **Published** too, the Library links to the page, and the page as published is kept in the editor's **History**. A late callback for an older send doesn't move the page's address back, and the same callback sent again changes nothing.+- `failed` marks the send **failed** with your reason, and the Library shows it. A send already marked published stays published. A callback that lands before your webhook answers keeps its word: the answer doesn't mark that send **sent** afterwards.+- You can call back before answering the webhook, or later. The callback shares the opportunity callback's limits: 1,200 requests per 15 minutes per secret for both together, and 10 failed attempts per 15 minutes per IP.+### `webhook.test````json@@ -201,6 +288,11 @@ The test uses the URL and secret currently in the form, so you can check an endp- Each event is sent **once**. There are no automatic retries.- Ansvisor waits up to 15 seconds for a response (10 seconds for `webhook.test`).- Respond with a 2xx status quickly and do slow work after responding.+- `content_draft.sent`:+ - A 2xx answer marks the send **sent**. Anything else, or no answer, marks it **failed**, and the Library shows why. Redirects aren't followed, and the first 2,000 characters of the answer are kept.+ - A single page is sent while the person waits. A bulk send (up to 25 pages) goes on in the background, one page after another, with a 2-second pause between pages.+ - A workspace can send 200 pages in 24 hours.+ - On Ansvisor Cloud the webhook must be a public address. A self-hosted install may also use addresses on its own network.<Card title="Help center" icon="circle-question" href="/faq">Common questions and troubleshooting.diff --git a/docs/guides/content-editor.mdx b/docs/guides/content-editor.mdxindex 9717e04a0..38ae0eff9 100644--- a/docs/guides/content-editor.mdx+++ b/docs/guides/content-editor.mdx@@ -147,7 +147,8 @@ The Content Agent never changes these passages. If you edit one, the editor asks- **Copy HTML** copies the whole page as HTML, HTML blocks and schema included, to paste into your CMS.- **Export** downloads the page as **Word**, **HTML** or **Markdown**. Only the HTML file carries the schema (JSON-LD).- **Add HTML** in the toolbar adds an HTML block: an embed, a widget or a form, kept exactly as written. Ansvisor never runs it. **Edit as HTML** shows the page's source; scripts, iframes and inline styles are removed when you switch back.-- **Mark ready** saves the page, sets it to **Ready** and keeps a version in History. If the draft was sent to the Action Center, it also completes its task there. Ansvisor doesn't publish the page: copy or export it to your site.+- **Send to CMS** (admins and managers) sends the page to your workflow tool through the brand's webhook, for it to create the post in your CMS. See [Send to CMS](/guides/send-to-cms).+- **Mark ready** saves the page, sets it to **Ready** and keeps a version in History. If the draft was sent to the Action Center, it also completes its task there. Ansvisor doesn't publish the page: copy or export it to your site, or send it to your CMS.- Click **Ready** in the header to move the page back to **In review**. A task that Mark ready completed is open again (**In Progress**), unless someone changed it in the Action Center since or the action is closed.## Library@@ -169,6 +170,7 @@ The columns are Content, Type, Method (Create or Optimize), By (you, the Content- **Status**: set the draft to In progress, In review, Ready or Published. Ready works like the editor's Mark ready, and moving a ready or published draft back to In progress or In review opens its task again, as the editor's **Ready** does.- **Export Word**, **Export HTML** or **Export Markdown** for that draft.+- **Send to CMS** (admins and managers, not for archived drafts). Beside each row's status, an icon shows its last send: on its way, sent, failed or published. Tick several rows to send up to 25 at once. See [Send to CMS](/guides/send-to-cms).- **Send to Archive** or **Restore** (admins and managers).- **Delete** (admins and managers): the draft leaves the Library for good, with its versions and suggestions. An Action Center task it was sent as stays.diff --git a/docs/guides/send-to-cms.mdx b/docs/guides/send-to-cms.mdxnew file mode 100644index 000000000..4332a97b4--- /dev/null+++ b/docs/guides/send-to-cms.mdx@@ -0,0 +1,93 @@+---+title: "Send to CMS"+description: "Send Content Editor pages to your CMS through your workflow tool, and see where they went live."+---++**Send to CMS** sends a Content Editor page to your brand's webhook as a content package: the page ready to publish, its title, slug, meta title, meta description, author and featured image. Your workflow tool (n8n, Make, Zapier or your own endpoint) turns it into a post or page in your CMS. Ansvisor never publishes on its own: your workflow decides whether the page lands as a draft or goes live.++When your workflow tells Ansvisor where the page went live, the draft becomes **Published** and its address shows in the Library.++## Before you start++1. Open **Content → Opportunities → Webhook Settings**.+2. Enter your workflow's webhook URL.+3. Set a **Secret key**. Ansvisor sends it with every request, signs each page with it, and your workflow needs it to report where a page went live.+4. Tick **Content page sent**. It is off by default, so a workflow built for opportunities doesn't receive pages it doesn't expect.+5. Save.++Only **admins and managers** can send pages.++## Send one page++- **From the editor:** click the paper-plane icon in the header. If **Before you publish** opens first, check it and click **Continue to send**.+- **From the Library:** open a row's **…** menu and pick **Send to CMS**.++The dialog fills the fields from the page, and you can change them before sending:++| Field | Filled from |+|---|---|+| **Slug** | The live page's address for an optimized page, else the title. Letters, digits, dots, `-` and `_`, up to 200 characters. |+| **Meta title** | The title. |+| **Meta description** | The page's first paragraph. |++The slug and meta you send are kept on the draft, so the next send starts from them.++The page goes as **Export** makes it: the HTML without its H1 (your CMS's title field carries it), with the byline line if your brand adds the byline to its content. Ansvisor holds the send while:++- a placeholder such as `[figure, source]` is still open (**Fill now** goes to it);+- the page has no title, or nothing under its title;+- the slug can't be used.++## Send several pages++In the **Library**, tick the rows to send (up to 25 at once) and click **Send to CMS** in the bar above the table. The dialog lists each page as **Ready**, or says why it can't go. A page that can't go is left out; fix it in the editor. Each page goes with the slug and meta of its last send, or the page's own.++The pages are sent one after another in the background, with a short pause between them so your CMS isn't flooded. The dialog follows them and says how many went, and you can close it at any time: the Library keeps following them. Very long pages go in more than one request, each once the one before has gone; closing the dialog while one waits stops the rest, and it says how many didn't go.++A workspace can send **200 pages in 24 hours**.++## See how a send went++Beside each row's status, the Library shows its last send:++| Icon | Meaning |+|---|---|+| Clock | On its way. |+| Paper plane | Your workflow took it (it answered with a 2xx status). |+| Red warning | It failed. Hover it to see what your workflow answered or reported, or why it couldn't be reached. |+| Blue link | Published. Click it to open the live page. |++## Build the workflow++Every workflow has the same three steps:++1. **Receive** the `content_draft.sent` package with a webhook trigger. Check the `X-Webhook-Secret` header, or the `X-Ansvisor-Signature` header, against your secret.+2. **Create** the post in your CMS from `page`, for example:++ | CMS field | Package field |+ |---|---|+ | Title | `page.title` |+ | Body / content | `page.html` |+ | Slug | `page.slug` |+ | SEO title | `page.metaTitle` |+ | SEO / meta description | `page.metaDescription` |+ | Author | `page.author` |+ | Featured image | `page.featuredImage.src` (alt text in `page.featuredImage.alt`) |+ | Schema / head code | `page.jsonLd` |++ Create it as a **draft** if someone should review it in the CMS first. When `page.method` is `optimize`, the page was made from the live page at `page.sourceUrl`: update that post instead of creating a new one.+3. **Report** how it went: when the post is published, send `POST` to the package's `callback_url` with `{ "status": "published", "url": "https://www.example.com/blog/pour-over" }` and your secret in the `X-Webhook-Secret` header. If your CMS refused it, send `{ "status": "failed", "reason": "…" }` instead.++ If the post is published later, run this step from your CMS's "post published" trigger. Keep the package's `delivery.id`, or the `callback_url` itself, with the post so the trigger can find it.++Answer the webhook quickly, within 15 seconds, and do slow work afterwards. Ansvisor sends each page once and doesn't retry, so a failed send is sent again from the Library.++<Tip>+**n8n:** Webhook node → your CMS node (WordPress, Webflow, Ghost…) or an HTTP Request node → HTTP Request node to `{{$json.body.callback_url}}`.++**Make:** Custom webhook → your CMS module → HTTP "Make a request" module to the callback URL.++**Zapier:** Webhooks by Zapier "Catch Hook" → your CMS action → Webhooks by Zapier "POST" to the callback URL.+</Tip>++The package's fields, the signature and the callback are described in [Webhooks](/api-reference/webhooks).diff --git a/docs/mint.json b/docs/mint.jsonindex 822656d2a..f91a50c3b 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -87,6 +87,7 @@"guides/competitors","guides/content-optimization","guides/content-editor",+ "guides/send-to-cms","guides/site-audit","guides/reports","guides/daily-pulse",