WonderRank Webhooks
Receive fully researched, SEO-optimized articles directly to your CMS or custom application via instantaneous HTTP POST requests. Complete with full lifecycle synchronization (publish, update, unpublish) and two-way live URL discovery.
Full Lifecycle Sync
Automatic event dispatching for first-time publishing, updates after editing, and unpublishing back to draft.
Two-Way Live URL
Return your live article URL in the JSON response to instantly unlock 1-click "View Live" buttons in WonderRank.
Immutable UUID Keying
Safe upserts by data.id ensure slug edits never create duplicate split records on your database.
Let Your AI Assistant Write The Endpoint
You do not need to write receiver boilerplate manually. Paste this prompt into Cursor, Claude Code, GitHub Copilot, or ChatGPT in your codebase. It builds the receiver adhering strictly to your project's existing stack and framework conventions.
I use WonderRank to write and publish SEO-optimized articles for my website. WonderRank will deliver every published, updated, or unpublished article to a webhook on my site. Build that webhook receiver in this project. Match the language, framework, and conventions this project already uses.
How WonderRank delivers:
- An HTTP POST with a JSON body, sent to a public https URL that I will configure in WonderRank.
- Every request carries my access token in an "Authorization: Bearer <token>" header. Read the expected token from an environment variable (e.g. WONDERRANK_WEBHOOK_SECRET), never hardcode it. I will copy the token from the WonderRank dashboard.
- Test deliveries carry "test": true. Real deliveries carry "test": false.
Event Types:
1. "article.published": Delivered when an article is published for the first time.
2. "article.updated": Delivered when an already-published article is edited and published again.
3. "article.unpublished": Delivered when an article is reverted to draft status in WonderRank (take it down or set status to draft).
The JSON body follows the Envelope Pattern:
// For "article.published" and "article.updated":
{
"event_id": "evt_8f3a2b1c9d4e",
"event": "article.published", // or "article.updated"
"test": false,
"occurred_at": "2026-10-09T12:00:00Z",
"data": {
"id": "7b8e5c3a-9f1d-4e2b-8a1c-3d4e5f6a7b8c",
"title": "How to Automate SEO",
"slug": "how-to-automate-seo",
"content_html": "<p>Article HTML body with embedded FAQ & schema...</p>",
"content_markdown": "Markdown body...",
"seo": {
"title": "How to Automate SEO (2026 Guide)",
"meta_description": "Learn the best strategies to...",
"target_keyword": "automate seo",
"schema_json_ld": "{...}"
},
"image": {
"url": "https://storage.wonderrank.com/blog-images/...",
"alt": "How to Automate SEO (2026 Guide)"
},
"authors": [{ "name": "Jane Doe", "linkedin": "...", "twitter": "...", "picUrl": "..." }],
"publisher": "Acme Inc",
"key_takeaways": ["Automate repetitive SEO tasks", "Use webhooks for instant CMS delivery"],
"faqs": [{ "q": "What is SEO?", "a": "Search Engine Optimization..." }],
"sources": [{ "claim": "Organic Traffic Study", "url": "https://example.com" }],
"tags": ["SEO", "Automation"]
}
}
// For "article.unpublished":
{
"event_id": "evt_8f3a2b1c9d4e",
"event": "article.unpublished",
"test": false,
"occurred_at": "2026-10-09T12:00:00Z",
"data": {
"id": "7b8e5c3a-9f1d-4e2b-8a1c-3d4e5f6a7b8c",
"slug": "how-to-automate-seo",
"title": "How to Automate SEO"
}
}
What the receiver must do:
1. Security: Compare the bearer token against my stored environment secret. Respond 401 on mismatch or missing header.
2. Testing: Respond 200 to test deliveries ("test": true) immediately without saving anything to the database.
3. Upsert Logic: For "article.published" and "article.updated", create or update the content on my site. Match on "data.id" (UUID) as the primary immutable identifier (fallback to "slug"). Repeat deliveries must update the existing post, never duplicate.
4. Unpublish Logic: For "article.unpublished", set the post's status to 'draft' or archive/unpublish it by "data.id" so it is no longer publicly visible.
5. Two-Way Live URL Response: On successful publish/update, respond with JSON returning the public live URL of the post:
{ "success": true, "url": "https://mybrand.com/blog/how-to-automate-seo" }
WonderRank automatically reads this "url" field and enables a direct "View Live" button in the dashboard!
6. SEO Injection: Store and render the SEO tags in served HTML: <title> from "seo.title", meta description from "seo.meta_description", og:image from "image.url", and inject "seo.schema_json_ld" into a <script type="application/ld+json"> tag in the HTML head.
7. Performance: Respond within 10 seconds. Process any heavy cache-invalidation or static sitemap rebuilding asynchronously so it does not block the HTTP response.
8. Routing: Ensure the endpoint route responds directly without trailing slash redirects (HTTP 301/308 redirects convert POST to GET and drop the request body).
"content_html" is sanitized and ready to render as-is (it includes WonderRank's injected FAQ accordions and source citations). "content_markdown" is the raw Markdown. Render "data.title" as the page's <h1> above the body: exactly one H1 per page.
When you are done, tell me:
1. The full relative URL path of the webhook (e.g. /api/webhooks/wonderrank) so I can configure it in WonderRank.
2. The environment variable name where I should save my WonderRank Webhook Secret.1. Setting Up Your Webhook
Configuring a webhook takes under 60 seconds in the WonderRank dashboard:
- Open Dashboard → Integrations → Webhooks.
- Select your website from the dropdown selector.
- Webhook Endpoint: Provide the public, secure HTTPS endpoint where your application listens (e.g.,
https://api.yourdomain.com/api/webhooks/wonderrank). - Access Token: Click Generate Secret. Copy this token (it begins with
wr_wh_). Store it as an environment variable in your receiver application (e.g.,WONDERRANK_WEBHOOK_SECRET). - Click Save Webhook, then click Test Webhook to verify the handshake.
2. Authentication & Secret Mechanism
Every request from WonderRank includes your secret access token inside standard HTTP authentication headers:
3. Lifecycle Events & Payload Schema
WonderRank delivers 3 distinct lifecycle events. Select an event below to preview its exact JSON payload:
{
"event_id": "evt_4a8f9b2c1d0e",
"event": "article.published",
"test": false,
"occurred_at": "2026-10-11T12:00:00Z",
"data": {
"id": "7b8e5c3a-9f1d-4e2b-8a1c-3d4e5f6a7b8c",
"title": "Programmatic SEO: The Definitive 2026 Playbook",
"slug": "programmatic-seo-definitive-playbook",
"content_html": "<div class=\"key-takeaways\">...</div><p>Programmatic SEO is the process...</p><h2>Frequently Asked Questions</h2><details class=\"faq-accordion\"><summary>How fast does programmatic SEO rank?</summary><p>Typically 4-8 weeks...</p></details><h2>Sources & Citations</h2><ol class=\"sources-list\"><li><a href=\"https://developers.google.com/search\">developers.google.com</a></li></ol><script type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[...]}<\/script>",
"content_markdown": "> **⚡ Key Takeaways**\n> • Scale high-intent pages...\n\nProgrammatic SEO is...\n\n## Frequently Asked Questions\n**How fast does it rank?**\nTypically 4-8 weeks...",
"seo": {
"title": "Programmatic SEO: The Definitive 2026 Playbook",
"meta_description": "Learn how to build high-converting programmatic SEO pages that dominate Google search results.",
"target_keyword": "programmatic seo",
"schema_json_ld": "{\n \"@context\": \"https://schema.org\",\n \"@graph\": [...]\n}"
},
"image": {
"url": "https://storage.wonderrank.com/blog-images/7b8e5c3a.png",
"alt": "Programmatic SEO Playbook 2026"
},
"authors": [
{
"name": "Alex Mercer",
"linkedin": "https://linkedin.com/in/alexmercer",
"twitter": "https://twitter.com/alexmercer",
"picUrl": "https://storage.wonderrank.com/authors/alex.jpg"
}
],
"publisher": "Acme SaaS",
"key_takeaways": [
"Scale high-intent programmatic pages with automated topical workflows.",
"Internal link architecture determines search engine crawl velocity."
],
"faqs": [
{
"q": "How fast does programmatic SEO rank?",
"a": "Typically 4 to 8 weeks depending on internal link architecture."
}
],
"sources": [
{
"claim": "Google Search Essentials Documentation",
"url": "https://developers.google.com/search",
"year": "2026"
}
],
"tags": ["SEO", "Growth"]
}
}| Property | Type | Description |
|---|---|---|
| event_id | string | Unique delivery attempt ID. Use for idempotency and logging. |
| event | string | article.published, article.updated, or article.unpublished. |
| test | boolean | true during dashboard test pings, false for real content. |
| data.id | string (UUID) | Permanent unique ID in WonderRank. Match & upsert on this ID. |
| data.title | string | Editorial headline. Render this as the page's single <h1> tag. |
| data.slug | string | URL-safe permalink slug. |
| data.content_html | string (HTML) | Full sanitized HTML body containing styled FAQ accordions, sources, and embedded JSON-LD. Ready to render as-is. |
| data.content_markdown | string (MD) | Raw Markdown source body if your CMS generates HTML natively. |
| data.seo.schema_json_ld | string (JSON) | Google-compliant Schema.org (BlogPosting + FAQPage). Inject into <head>. |
| data.image.url | string (URL) | Public CDN URL of the featured banner image. |
| data.authors | array of objects | Author E-E-A-T credentials including name, linkedin, twitter, and picUrl. |
| data.publisher | string | Publishing brand / company entity name. |
| data.key_takeaways | string[] | Key bullet takeaways and summary answers for the top of the article. |
| data.faqs | array of objects | Structured Q&A pairs (q, a) for custom FAQ components. |
| data.sources | array of objects | Citations used during research (claim, url, year). |
| data.tags | string[] | Category taxonomies and topic tags. |
4. Two-Way Live URL Handshake
When WonderRank delivers an article, your endpoint should respond with HTTP 200 and return the canonical public URL where the article is live:
WonderRank automatically reads the "url" property and unlocks a direct "View Live ↗" button in your WonderRank Editor, Content Plan, and Library!
5. Complete Receiver Examples
Copy and adapt a production-ready webhook receiver in your stack of choice:
import { NextResponse } from 'next/server';
import crypto from 'crypto';
const EXPECTED_SECRET = process.env.WONDERRANK_WEBHOOK_SECRET;
function safeCompare(a: string, b: string): boolean {
if (!a || !b) return false;
const bufA = Buffer.from(a);
const bufB = Buffer.from(b);
if (bufA.length !== bufB.length) return false;
return crypto.timingSafeEqual(bufA, bufB);
}
export async function POST(req: Request) {
// 1. Verify Authentication Token with Constant-Time Comparison
const authHeader = req.headers.get('authorization');
if (!authHeader || !authHeader.startsWith('Bearer ')) {
return NextResponse.json({ error: 'Missing Bearer token' }, { status: 401 });
}
const token = authHeader.split(' ')[1];
if (!EXPECTED_SECRET || !safeCompare(token, EXPECTED_SECRET)) {
return NextResponse.json({ error: 'Invalid access token' }, { status: 401 });
}
const payload = await req.json();
// 2. Respond immediately to test health checks
if (payload.test === true) {
return NextResponse.json({ success: true, message: 'Test connection verified' });
}
const { event, data } = payload;
try {
// 3. Handle Publish & Update (Idempotent Upsert on data.id)
if (event === 'article.published' || event === 'article.updated') {
await db.post.upsert({
where: { id: data.id },
create: {
id: data.id,
title: data.title,
slug: data.slug,
contentHtml: data.content_html,
contentMarkdown: data.content_markdown,
metaTitle: data.seo?.title,
metaDescription: data.seo?.meta_description,
schemaJsonLd: data.seo?.schema_json_ld,
imageUrl: data.image?.url,
status: 'published',
},
update: {
title: data.title,
slug: data.slug,
contentHtml: data.content_html,
contentMarkdown: data.content_markdown,
metaTitle: data.seo?.title,
metaDescription: data.seo?.meta_description,
schemaJsonLd: data.seo?.schema_json_ld,
imageUrl: data.image?.url,
status: 'published',
},
});
// Two-Way Handshake: Return the live URL so WonderRank enables the "View Live" button!
const postUrl = `https://yourdomain.com/blog/${data.slug}`;
return NextResponse.json({ success: true, url: postUrl });
}
// 4. Handle Unpublish (Revert to Draft)
if (event === 'article.unpublished') {
await db.post.update({
where: { id: data.id },
data: { status: 'draft' },
});
return NextResponse.json({ success: true, message: 'Article reverted to draft' });
}
return NextResponse.json({ success: true, message: 'Unhandled event ignored' });
} catch (error: any) {
console.error('Webhook error:', error);
return NextResponse.json({ error: 'Internal storage error' }, { status: 500 });
}
}6. Testing Your Webhook
You can test your endpoint through two methods:
Method 1: Instant Ping Test
In Integrations → Webhooks, click Test Webhook. WonderRank sends a ping carrying "test": true. Your receiver verifies authentication and responds with 200 without saving to the DB.
Method 2: Live Article Publish
Open any generated draft in the Content Editor and click Publish Now. Inspect your receiver logs to verify the article body, SEO metadata, and JSON-LD schema are received and saved.
7. Troubleshooting Common Issues
Endpoint not receiving requests or timing out
Ensure your endpoint is publicly accessible over HTTPS (localhost will not work; use ngrok or Cloudflare Tunnels for local testing). WonderRank delivers with a strict 10-second timeout. Any heavy tasks like static sitemap generation or image processing must be run asynchronously after responding with HTTP 200.
401 Unauthorized errors
Verify that your environment variable matches the exact secret in WonderRank Integrations. Check that your receiver strips the "Bearer " prefix before comparing tokens.
Trailing slash redirects (301/308 dropping POST body)
Frameworks like Next.js often redirect URLs ending with a slash (e.g. /webhook/ → /webhook). HTTP redirects convert POST requests into GET requests and discard the JSON payload. Ensure your configured URL exactly matches your framework's route.
Duplicate articles on republish
Always use data.id as your database primary key for upserting content. Do not match solely on slug, because changing an article title in WonderRank generates a new slug, which would duplicate records if matched by slug alone.
Table of Contents
Need a webhook now?
Head over to your dashboard and generate your unique secret token in 1 click.
Configure Integrations →