Skip to content
RankboardSEO
Custom webhook

Publishing integration

Connect Custom webhook to Rankboard

Receive Rankboard article payloads in your own application or CMS.

Content type
How-to
Number of steps
5 steps
Estimated time
About 15 min
Reviewed
Aug 23, 2026
On this page

In this guide

What you will complete

You will create an authenticated HTTPS endpoint, handle Rankboard's article payload, and pass the built-in connection test.

  1. 1Create a public POST endpoint
  2. 2Validate the shared secret
  3. 3Validate and store the blog payload
  4. 4Return a useful response
  5. 5Connect and run the built-in test

What you need

Collect these details before you start the connection.

Webhook URL
A public HTTPS endpoint that accepts POST requests
Secret
A strong shared secret stored by both applications
Response
Any 2xx response; JSON can return id and publishedUrl

Connect Custom webhook

Complete each step in order. Provider screenshots link to their original documentation.

  1. 1

    Create a public POST endpoint

    Add an HTTPS route in your application, for example /api/blogs/webhook. It must accept JSON from Rankboard's servers and must not require a browser session or CSRF cookie.

  2. 2

    Validate the shared secret

    Generate a strong random secret and store it in your receiving application, for example as BLOG_WEBHOOK_SECRET. Rankboard sends the same value in both the Authorization: Bearer header and X-Blog-Webhook-Secret header.

  3. 3

    Validate and store the blog payload

    Require blog.source to equal rankboard, validate the slug and status, then create or update the article using blog.externalId as the stable source identifier. Keep draft payloads private.

  4. 4

    Return a useful response

    Return a 2xx response after the content is safely stored. A JSON response with id, url, or publishedUrl lets Rankboard keep the remote post ID and public link with the article.

  5. 5

    Connect and run the built-in test

    In Rankboard, select Settings → Integrations → Webhook. Enter the endpoint and shared secret, then select Connect Webhook. Rankboard immediately sends a draft connection-test payload.

    Example webhook Recent Deliveries log with successful deliveries
    Example from GitHub's webhook docs: a delivery log should show successful requests after Rankboard sends its test. Your own server or webhook tester will look different. Source: GitHub webhook documentation ↗

Data Rankboard sends

Review the data this integration reads or writes before you connect it.

  • blog.slug, title, description, and Markdown content
  • blog.publishedAt and a status of draft or published
  • blog.featuredImage and featuredImageAlt when available
  • blog.source set to rankboard and a stable blog.externalId
  • The shared secret in two request headers, never in the URL

Handle the request and response

Rankboard sends JSON by POST. Authenticate the request, validate the article, then return a successful response.

Expect Content-Type: application/json. Rankboard sends the shared secret in the Authorization and X-Blog-Webhook-Secret headers.

{
  "blog": {
    "slug": "example-article",
    "title": "Example article",
    "description": "Search result description",
    "content": "# Markdown article content",
    "publishedAt": "2026-08-23T12:00:00.000Z",
    "featuredImage": "https://cdn.example.com/image.png",
    "featuredImageAlt": "Descriptive alternative text",
    "status": "draft",
    "source": "rankboard",
    "externalId": "stable-rankboard-article-id"
  }
}

Return a JSON body so Rankboard can store the remote article ID and public URL.

{
  "ok": true,
  "id": "your-cms-post-id",
  "slug": "example-article",
  "publishedUrl": null
}

Return a public URL only for published content. Rankboard also accepts a field named url. Keep draft URLs null or private.

Confirm the connection works

Run one draft test and verify the result before you enable direct publishing.

  1. Saving the connection sends a draft named Rankboard connection test with the slug rankboard-connection-test.
  2. Return 2xx only after authentication and payload validation pass. Rankboard treats every non-2xx response as a failed connection or publish.
  3. Send a real article as a draft and confirm your receiver stores it privately before enabling published status.

Fix common connection errors

Match the error to the issue below, then retry the connection.

Rankboard says the webhook cannot be reached.

Confirm the URL is public HTTPS, accepts POST, has a valid certificate, and is not restricted to localhost, a VPN, or browser-only authentication.

The endpoint returns 401 or 403.

Compare the shared secret stored by your app with the value saved in Rankboard. Trim accidental whitespace and accept either the Bearer header or X-Blog-Webhook-Secret.

Publishing succeeds but Rankboard has no public link.

Return JSON containing publishedUrl or url after a published payload. Draft responses can return null because drafts should not have a public URL.

Protect your credentials

Limit access, keep secrets private, and revoke credentials when the connection is no longer needed.

  • Use HTTPS and compare secrets in constant time when your framework makes that possible.
  • Reject invalid source, title, slug, or status values before writing data.
  • Do not log the Authorization header or shared secret. Rotate the secret by updating both applications together.
  • Make article writes idempotent by updating on externalId instead of creating a duplicate on every retry.

Read the Privacy Policy and Terms & Conditions for service-wide data terms.

Get implementation help

The webhook runs on your endpoint. If this contract does not cover your framework or CMS, open the support form below.