Webhook

How it works

Webhook is the “everything else” integration. Use it for Next.js ISR triggers, Vercel deploy hooks, Make / Zapier / n8n flows, or a custom Rails / Django / PHP / Express backend.

SEORAV signs and POSTs the full canonical article payload to your endpoint. What happens next is yours: write to a database and revalidate, commit a markdown file to Git and trigger a deploy, push into Sanity / Strapi, fan out to multiple destinations — the receiver is your code. We retry on failure, log every attempt, and re-fetch the live URL after publish to score it against 17 rendered-HTML checks.

Setup

1. 1

   Expose a public HTTPS POST endpoint

   The endpoint must be reachable from the public internet. Loopback, RFC1918 (10/8, 172.16/12, 192.168/16), link-local, and metadata-service IPs are blocked at connect time and re-checked before every send. For local development, use cloudflared tunnel or ngrok.

2. 2

   Generate a signing secret

   Run on your machine:

   shell

   openssl rand -hex 32

   Keep the hex string. We sign with it; you verify with it.

3. 3

   Connect inside SEORAV

   In the dashboard, go to Integrations → Connect → Webhook. Paste your URL and the secret. We immediately fire a connect.testevent with a UUID nonce. Your endpoint must respond 2xx within 10 seconds. Optionally, return {"echo": "<the nonce>"}in the body so we can confirm you’re parsing the JSON, not just blanket-200’ing.

4. 4

   Approve an article and watch it flow

   When you approve a generated article in SEORAV, we POST a post.publishevent to your URL. Your activity timeline in Integrations → [your hook]shows the request, status, latency, and retry plan.

What we send

Every event has the same envelope: { event, data, integration_hints }. The data.postobject is the canonical article — every field SEORAV knows about, fully populated. You can ignore fields you don’t need; missing fields are typed as null in our payload, never absent.

Request headers

Routing articles vs answer pages (and future modules)

SEORAV ships at least two payload kinds through your webhook: long-form article events and FAQ-style answer_page events. New modules (case studies, comparisons, glossary entries) will use the same envelope with a different entity_type. Your receiver must either route by entity_type or be content-shape-agnostic.

Two patterns work, pick whichever fits your stack:

One endpoint, internal routing. One webhook URL receives everything. Your handler reads the X-Entity-Type header (ordata.post.entity_type) and dispatches to the right destination — a different collection, a different DB table, or a different downstream service.

Multiple endpoints, per-module URLs.Inside SEORAV, open the CMS connection and add a per-entity destination override. Articles continue to POST to the connection’s primary URL; answer pages POST to a separate URL you set in the Publish channels section. Use this if your serverless stack is easier to maintain as several small functions than one big router.

Either way, the payload always includes entity_type in the body AND in the headers, and SEORAV signs each event with the same HMAC secret regardless of destination.

Example payload

Here is a post.publish body for a real article. Fields without values are explicit null, not omitted, so your TypeScript types stay sound.

{
  "event": "post.publish",
  "data": {
    "post": {
      "entity_type":      "article",
      "entity_id":        "9b1c5e0a-7a7e-4d1d-b2cb-2f5b41a0c0e2",
      "site_id":          "1f3a09a8-2a3e-4b1f-a4d6-5fabb4ab27ee",
      "org_id":           "5c5f56a9-8b1a-4d2e-a8be-0a3a8a1c2c4d",
      "title":            "How to choose a reverse-osmosis system in 2026",
      "slug":             "how-to-choose-reverse-osmosis-system-2026",
      "body_markdown":    "## What you actually need to know …",
      "body_html":        "<h2>What you actually need to know</h2><p>…</p>",
      "excerpt":          "Skip the spec sheet. The three things that matter are membrane stage count, recovery rate, and remineralisation.",
      "meta_title":       "Reverse osmosis systems · the 3 specs that matter (2026)",
      "meta_description": "Membrane stages, recovery rate, remineralisation — the three specs that change your RO water tomorrow. Independent guide, no affiliate links.",
      "canonical_url":    "https://yoursite.com/blog/how-to-choose-reverse-osmosis-system-2026",
      "og_title":         "Reverse osmosis systems · the 3 specs that matter",
      "og_description":   "Membrane stages, recovery rate, remineralisation. Plain-English explanation of the only three RO specs that actually change your water.",
      "og_image":         "https://cdn.seorav.com/articles/9b1c5e0a/hero.webp",
      "jsonld_blocks": [
        { "@context": "https://schema.org", "@type": "Article", "headline": "How to choose a reverse-osmosis system in 2026", "datePublished": "2026-04-27T08:00:00Z" },
        { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ /* … */ ] }
      ],
      "tags":             ["reverse osmosis", "water filtration", "buying guide"],
      "categories":       ["guides"],
      "author_ref":       "elena-vance",
      "hero_image_url":   "https://cdn.seorav.com/articles/9b1c5e0a/hero.webp",
      "hero_image_alt":   "Three reverse-osmosis systems lined up on a kitchen counter",
      "scheduled_for":    null,
      "publish_mode":     "publish",
      "source_url_on_platform": null
    },
    "mode": "publish"
  },
  "integration_hints": {
    "render_jsonld_in_head":     true,
    "render_canonical_link_rel": true,
    "render_meta_description":   true,
    "render_opengraph":          true,
    "publish_url_field":         "url",
    "required_response_fields":  ["post_id", "url", "status"]
  }
}

integration_hints object

Every post.publish / post.update event carries anintegration_hintsobject that tells your receiver, in machine-readable form, what SEORAV expects you to do with the payload. Cheap to ignore if you already know — invaluable when you’re wiring a fresh receiver. Not sent on connect.test or post.unpublish.

Answer-page extras (when entity_type = “answer_page”)

FAQ / answer-engine pages flow through the same webhook envelope as articles. They carry every core field listed in the article properties table below (title, slug, body_markdown, meta_*, jsonld_blocks, etc.) PLUS the following top-level extras — flattened from the canonical extra object so your receiver can read them without parsing the body. They are present only when entity_type === "answer_page".

Article properties

Verify the signature

Compute HMAC-SHA256 over the rawbody — not a re-serialised JSON. Whitespace differences will silently break verification, and you’ll spend 30 minutes wondering why your tests pass and prod doesn’t.

Python (FastAPI / Flask)

import hmac, hashlib
from datetime import datetime, timezone
from fastapi import FastAPI, Request, HTTPException

SECRET = b"<your-hmac-secret>"
MAX_SKEW_SECONDS = 5 * 60                # reject deliveries older than 5 min

app = FastAPI()
seen_deliveries: set[str] = set()        # use Redis / DB in prod

@app.post("/seorav-webhook")
async def receive(req: Request):
    raw = await req.body()               # MUST be raw bytes, not parsed JSON

    sig_header = req.headers.get("x-seorav-signature", "")
    if not sig_header.startswith("sha256="):
        raise HTTPException(401, "missing signature")
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig_header.removeprefix("sha256="), expected):
        raise HTTPException(401, "bad signature")

    # Replay window
    ts = req.headers.get("x-seorav-timestamp")
    sent_at = datetime.fromisoformat(ts.replace("Z", "+00:00"))
    if abs((datetime.now(tz=timezone.utc) - sent_at).total_seconds()) > MAX_SKEW_SECONDS:
        raise HTTPException(401, "stale request")

    # Idempotency
    delivery = req.headers.get("x-seorav-delivery", "")
    if delivery in seen_deliveries:
        return {"post_id": delivery, "url": "", "status": "duplicate"}
    seen_deliveries.add(delivery)

    body = await req.json()
    post = body["data"]["post"]
    # …persist to your DB / write file / trigger ISR…
    return {"post_id": post["slug"], "url": f"https://yoursite.com/blog/{post['slug']}", "status": "published"}

Node.js (Next.js Route Handler)

// app/api/seorav-webhook/route.ts  (Next.js App Router)
import crypto from "node:crypto"
import { revalidatePath } from "next/cache"

const SECRET = process.env.SEORAV_SECRET!
const MAX_SKEW = 5 * 60_000

export async function POST(req: Request) {
  const raw = await req.text()                                  // raw, NOT .json()
  const sig = req.headers.get("x-seorav-signature") ?? ""
  const ts  = req.headers.get("x-seorav-timestamp") ?? ""

  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(raw).digest("hex")
  const sigBuf   = Buffer.from(sig)
  const expBuf   = Buffer.from(expected)
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return new Response("bad signature", { status: 401 })
  }
  if (Math.abs(Date.now() - Date.parse(ts)) > MAX_SKEW) {
    return new Response("stale", { status: 401 })
  }

  const { event, data } = JSON.parse(raw)
  if (event === "post.publish" || event === "post.update") {
    // upsert into your DB by data.post.slug, then:
    revalidatePath(`/blog/${data.post.slug}`)
  }
  return Response.json({
    post_id: data.post.slug,
    url:     `https://yoursite.com/blog/${data.post.slug}`,
    status:  "published",
  })
}

Go (net/http)

package webhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "math"
    "net/http"
    "strings"
    "time"
)

const maxSkew = 5 * time.Minute

func Handler(secret []byte) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        body, _ := io.ReadAll(r.Body)
        sig := strings.TrimPrefix(r.Header.Get("X-SEORAV-Signature"), "sha256=")
        sent, _ := hex.DecodeString(sig)
        mac := hmac.New(sha256.New, secret); mac.Write(body)
        if !hmac.Equal(sent, mac.Sum(nil)) { http.Error(w, "bad sig", 401); return }

        ts, _ := time.Parse(time.RFC3339, r.Header.Get("X-SEORAV-Timestamp"))
        if math.Abs(time.Since(ts).Seconds()) > maxSkew.Seconds() { http.Error(w, "stale", 401); return }

        // … persist + respond …
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte(`{"post_id":"…","url":"…","status":"published"}`))
    }
}

What we expect back

Respond 2xx within 30 seconds with the published URL. We re-fetch that URL afterwards and run the 17-check rendered-HTML scorer (title in <head>, canonical link, JSON-LD parses, meta description present, …). If you don’t return a URL we fall back to canonical_url. If neither is set, scoring is skipped — you can still publish, you just lose the post-publish report.

{
  "post_id":  "<your-internal-id-or-our-slug>",
  "url":      "https://yoursite.com/blog/the-published-slug",
  "status":   "published",  // or "scheduled" | "draft"
  "message":  "<optional human-readable note>",
  "echo":     "<X-SEORAV-Delivery — only on connect.test for round-trip proof>"
}

Activity timeline

Every delivery is logged on your connection page. A successful publish flow looks like this:

A failure with retries looks like this:

Retries

Any non-2xx, network error, or timeout triggers retry with exponential backoff. You will see deliveries again — design your endpoint to be idempotent on X-SEORAV-Delivery.

Attempt 1 → ~1 minute later
Attempt 2 → ~5 minutes
Attempt 3 → ~25 minutes
Attempt 4 → ~2 hours
Attempt 5 → ~10 hours
Attempt 6 → ~2 days   (after this, dead-lettered)

Dead-lettered jobs surface in the connection’s activity feed with a manual Retry button. Clicking it resets the schedule.

Reachability & SSRF guard

Webhook URLs are validated at connect time and re-resolved before every send. We reject any host that resolves to a private, loopback, link-local, multicast, or cloud-metadata address — even after a redirect, even if DNS flips after-the-fact (rebinding defence). For local dev, expose your endpoint with Cloudflare Tunnel or ngrok and use the public hostname.

After publishing — make it shine

Best practices

• Read the body as raw text first, then verify, then parse JSON. Frameworks that auto-parse will silently break HMAC.
• Constant-time compare with hmac.compare_digest / crypto.timingSafeEqual. String equality leaks timing.
• Persist X-SEORAV-Delivery for at least 7 days. Dead-lettered retries can arrive up to 2 days late, and a manual retry could fire after that.
• Respond 200 fast, do work async. If your DB write or build step takes longer than 30 seconds, ack the webhook and process in a queue. Slow 200s cause us to timeout and retry.
• Never log the secret or signature. Either is enough to forge requests if leaked.
• Rotate periodically. Today, rotation = delete + recreate the connection. We’ll add a rotate-in-place button when enough customers ask.

Troubleshooting

Receiver returns 401 / signature mismatch

Almost always whitespace. Make sure you’re computing HMAC over the exact bytes we sent, before any framework re-serialises the JSON. Print both the bytes you verified and the bytes you parsed — they should be byte-for-byte identical.

Deliveries timing out (504)

We give you 30 seconds. If your handler kicks off a build or runs an LLM call inline, respond 200 first and process async. Long-running 200s look identical to failures from our side.

“Webhook URL rejected by SSRF guard”

The URL resolves to a private or loopback IP. Check that your-domain.comactually resolves to a public IP. If you’re behind Cloudflare, make sure proxy is enabled. For local dev, use a tunnel.

Verifier reports “url missing”

Your response didn’t include a url field, and no canonical_url is set on the SEORAV site. Either return the live URL, or set the canonical base URL in Settings → Site → Canonical URL.

Security