WonderRankWonderRankDOCS
Official Integration Protocol

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.

AI

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.

Cursor / Claude Prompt (Full Protocol Baked In)
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:

  1. Open Dashboard → Integrations → Webhooks.
  2. Select your website from the dropdown selector.
  3. Webhook Endpoint: Provide the public, secure HTTPS endpoint where your application listens (e.g., https://api.yourdomain.com/api/webhooks/wonderrank).
  4. 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).
  5. 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:

// HTTP Request Headers
POST /api/webhooks/wonderrank HTTP/1.1
Host: api.yourdomain.com
Authorization: Bearer wr_wh_9a8b7c6d5e4f3a2b1c...
Content-Type: application/json
User-Agent: WonderRank/2.0 Webhook
Security Best Practice: Never expose your webhook secret in client-side code or public git repositories. If a secret is ever compromised, rotate it immediately in the Integrations tab.

3. Lifecycle Events & Payload Schema

WonderRank delivers 3 distinct lifecycle events. Select an event below to preview its exact JSON payload:

Payload Structure — article.published
{
  "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 &amp; 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"]
  }
}
PropertyTypeDescription
event_idstringUnique delivery attempt ID. Use for idempotency and logging.
eventstringarticle.published, article.updated, or article.unpublished.
testbooleantrue during dashboard test pings, false for real content.
data.idstring (UUID)Permanent unique ID in WonderRank. Match & upsert on this ID.
data.titlestringEditorial headline. Render this as the page's single <h1> tag.
data.slugstringURL-safe permalink slug.
data.content_htmlstring (HTML)Full sanitized HTML body containing styled FAQ accordions, sources, and embedded JSON-LD. Ready to render as-is.
data.content_markdownstring (MD)Raw Markdown source body if your CMS generates HTML natively.
data.seo.schema_json_ldstring (JSON)Google-compliant Schema.org (BlogPosting + FAQPage). Inject into <head>.
data.image.urlstring (URL)Public CDN URL of the featured banner image.
data.authorsarray of objectsAuthor E-E-A-T credentials including name, linkedin, twitter, and picUrl.
data.publisherstringPublishing brand / company entity name.
data.key_takeawaysstring[]Key bullet takeaways and summary answers for the top of the article.
data.faqsarray of objectsStructured Q&A pairs (q, a) for custom FAQ components.
data.sourcesarray of objectsCitations used during research (claim, url, year).
data.tagsstring[]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:

// Your Receiver's HTTP 200 Response:
{ "success": true, "url": "https://yourdomain.com/blog/programmatic-seo-definitive-playbook" }

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:

app/api/webhooks/wonderrank/route.ts
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.