If you don't use WordPress but your own CMS, a shop or an automation such as Make or n8n, the SEO calendar sends approved posts directly to your system by webhook. FlowSEO sends the finished text as JSON to an address of your choice and signs every message so you can verify that it comes from us. This guide is for the person setting up the receiving end.
Create a webhook
- Open the SEO calendar and click Manage automations.
- Under Publishing, click Connect WordPress or a webhook.
- Under Kind of connection, choose Webhook.
- Optionally enter a name and put the address of your receiver under Webhook address. Only https is allowed, and FlowSEO doesn't follow redirects.
- Optional: expand Custom header (optional) and enter a header FlowSEO sends with every message, for example
Authorizationwith the valueBearer <your token>orX-Api-Key. More in the section “Custom header” below. - Click Save and check.
FlowSEO then shows the Webhook secret once. Copy it with Copy and store it in your system, as it is only shown now. The new connection is then available for selection under Publishing. Click Save so the calendar uses it.
When you save, FlowSEO sends a test message of the type ping, which contains only domain.host in data. If your receiver doesn't respond with a 2xx status, “Connection saved, the check failed:” appears with the reason.
In the same dialog, What the message looks like shows the headers, a complete example with your domain, the signature check in PHP and Node.js and how FlowSEO treats your answer. The example is built by the same code FlowSEO sends with.
What FlowSEO sends
Every message is a POST with JSON content. On the scheduled date, an event of the type content.published arrives. Shortened, it looks like this:
{
"id": "6f1c2a9e-5b7d-4c3e-9a10-2f8e4d6b1c55",
"type": "content.published",
"created_at": "2026-11-12T09:41:00+01:00",
"data": {
"domain": { "uuid": "…", "host": "example.com" },
"publish_at": "2026-11-12T09:41:00+01:00",
"previous": null,
"content": {
"uuid": "…",
"type": "guide",
"language": "en",
"main_keyword": "dining table for small spaces",
"title": "Dining table for small spaces: 7 ideas",
"slug": "dining-table-for-small-spaces",
"meta_title": "…",
"meta_description": "…",
"og_title": "…",
"og_description": "…",
"planned_url": "https://example.com/guides/dining-table-for-small-spaces",
"version": 3,
"html": "<p>…</p>",
"markdown": "…",
"json_ld": [
{ "@context": "https://schema.org", "@type": "BlogPosting", "headline": "…" }
],
"images": [
{ "role": "hero", "url": "https://…", "alt": "…", "title": "…", "caption": "…", "section_key": null }
]
}
}
}
Important for your implementation:
htmlandmarkdowncontain the text without the title. Take the title fromtitle.imagescontains the finished images with role, alt text and caption, the hero image first.json_ldis a list of schema.org objects you can embed as is in a<script type="application/ld+json">.previousis filled for an update, with theexternal_idandurlof the earlier publication. This lets you overwrite an existing post instead of creating a new one.
Verify the signature
Every message has three headers according to the “Standard Webhooks” standard:
webhook-id: the unique ID of the message, identical toidin the JSON.webhook-timestamp: the time of sending in seconds since 1970.webhook-signature: the signature in the formatv1,<Base64>.
The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body}. The key is the webhook secret exactly as FlowSEO showed it, as text. Ready-made Standard Webhooks libraries expect a secret prefixed with whsec_, though, so they don't fit as is; the few lines below are enough. In PHP, the check looks like this:
$base = $id.'.'.$timestamp.'.'.$rawBody;
$expected = 'v1,'.base64_encode(hash_hmac('sha256', $base, $secret, true));
$valid = hash_equals($expected, $signatureHeader);
In Node.js:
const crypto = require('node:crypto');
const expected = 'v1,' + crypto.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64');
const valid = signatureHeader.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
Always use the unmodified raw body of the request, not a re-encoded JSON. Also check that the timestamp isn't too old, for example at most five minutes, and process each webhook-id only once: every repetition of the same delivery carries the same webhook-id. That way no duplicate post appears when your answer didn't reach FlowSEO once.
Custom header
If your receiver expects its own credential, such as a token, you store exactly one header with name and value. FlowSEO sends it with every message, the ping included.
- The name consists only of letters, digits and the characters
! # $ % & ' * + - . ^ _ ` | ~, without spaces.Authorizationis allowed. Headers FlowSEO sets itself (webhook-id,webhook-timestamp,webhook-signature,Content-Type,Content-Length,Host,User-Agentand connection headers such asConnectionorTransfer-Encoding) can't be overwritten. - The value is one line without line breaks. It is stored encrypted and never shown again; the dialog only shows Set. If you leave the field empty when editing, the stored value stays as long as the webhook address stays the same. If you change the address, enter the value again, so it never goes to another receiver unnoticed.
- Remove header deletes it again, as does emptying the name and saving.
- The header is not part of the signature. Check it as well if you use it for access control, and rely on the signature for where the message comes from.
Report back the published address
If your system responds with a 2xx status and JSON such as {"url": "https://example.com/guides/dining-table-for-small-spaces", "id": "4711"}, FlowSEO records this address as the published address. Instead of url, the field can also be called link. Any other successful response counts as delivered, just without an address. An address outside your domain isn't accepted.
If something doesn't work
When you save a connection, FlowSEO gives the reason:
- “The other side refused the request.” Your receiver responded with an error status, often because of a failed signature check. Check that you're using the raw body and the right secret.
- “The address redirects. Please enter the final address.” Enter the address where the request actually lands.
- “The address is not publicly reachable or not https.” The receiver must be reachable over https from the internet.
- “The connection timed out.” FlowSEO waits at most 60 seconds. Respond immediately and process the post in the background afterwards.
Redirects (3xx) and answers with 401, 403, 404, 410 or any other 4xx status end the delivery right away. For timeouts, connection errors, status 408 and 429 and server errors (5xx), FlowSEO retries delivery, up to three times in total, after one and after five minutes. If it finally fails, the calendar shows “Publishing failed:” followed by the reason. How to reschedule is explained in WordPress publishing doesn't work.
Lost the secret? Our team generates a new secret for an existing connection, and the old one stops working immediately. Alternatively, create a new webhook connection and select it in the calendar.