Developer guide · v1

Irizpro Publish API

Connect any website to the Irizpro SEO platform. You add one HTTPS endpoint that follows this guide; from then on every article approved in Irizpro is delivered to it automatically and published on your site. It works with any technology: PHP, Node.js, Next.js, Python, a headless CMS or your own database.

Quick start

1. The site owner opens Irizpro → SEO Blog → Settings → Publish destination → Your Website (Publish API), enters the endpoint URL you will create, and clicks Connect. Irizpro issues the site’s Site ID and Signing Secret (its passport) and the owner sends them to you with “Copy setup for developer”.
2. Download the receiver for your stack, set the two values as environment variables, and fill in the one function that saves a post in your system.
3. Deploy it, then the site owner clicks Send test. Irizpro checks your endpoint against this guide and lists anything to fix. When all checks pass, articles flow automatically.

The request

Irizpro sends POST to your endpoint with a JSON body (UTF-8) and these headers. It waits up to 30 seconds for your reply and does not follow redirects.

Verify the signature

Every request is signed with your Signing Secret (HMAC-SHA256), the same scheme Stripe and GitHub use for webhooks. Verify it before doing anything else, on the raw body. Reject old timestamps to block replays.

timestamp = header "X-Irizpro-Timestamp"
signature = header "X-Irizpro-Signature"          // "sha256=<hex>"
raw       = the request body, exact bytes, BEFORE JSON parsing

reject (401) if |now - timestamp| > 300 seconds
expected  = "sha256=" + hex( HMAC_SHA256( key = SIGNING_SECRET, message = timestamp + "." + raw ) )
reject (401) unless constant_time_equals(expected, signature)
reject (401) unless json.site_id == SITE_ID

Example in PHP: hash_equals('sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret), $sig). All receivers below already do this.

The article payload

{
  "spec": "irizpro.publish.v1",
  "event": "post.publish",            // or "post.test"
  "test": false,                      // true for "post.test": validate, never save
  "delivery_id": "6f1c0b1e-…",        // unique per request
  "site_id": "site_9a1b2c3d4e5f6a7b",
  "sent_at": "2026-10-17T09:30:00.000Z",
  "post": {
    "external_id": "e6f6f634-ea21-4a85-af9d-eb8213e1d319",  // stable per article: same id = update
    "slug": "whatsapp-appointment-reminders-clinics",
    "title": "How WhatsApp Appointment Reminders Cut No-Shows",
    "content_html": "<p>…</p><h2>…</h2>…",   // body: NO <h1>, NO hero image
    "full_html": "<h1>…</h1><figure>…</figure><p>…</p>…",  // complete article, if you prefer it
    "excerpt": "Use WhatsApp reminders to cut no-shows…",
    "seo": {
      "meta_title": "WhatsApp Appointment Reminders | Reduce No-Shows",
      "meta_description": "Use WhatsApp appointment reminders…",
      "focus_keyword": "whatsapp appointment reminders",
      "keywords": ["whatsapp appointment reminders", "clinic no-shows"]
    },
    "featured_image": { "url": "https://…/featured.jpg", "alt": "…" },   // or null
    "author": { "name": "Nidhi" },          // or null
    "categories": ["Insights"],
    "tags": ["clinic no-shows"],
    "faqs": [{ "question": "…", "answer": "…" }],
    "schema": { "article": { "@type": "Article", … }, "faq": { "@type": "FAQPage", … } },
    "published_at": "2026-10-17T09:30:00.000Z",
    "language": "en"
  }
}

New optional fields may be added to v1 over time; ignore fields you don’t use. Anything breaking would ship as v2 with its own spec value.

Test vs publish

• post.publish: create the post, or update it if post.external_id already exists. Never create two posts for the same external_id.
• post.test ("test": true): sent by the “Send test” button. Verify and validate everything, then reply { "ok": true, "test": true, "action": "validated" }. Never save a test.

Your reply

Reply with JSON. On success use HTTP 200 and include the post’s public URL; Irizpro shows it as the published link and opens the page to check it.

HTTP 200
{ "ok": true, "url": "https://example.com/blog/whatsapp-appointment-reminders-clinics", "id": "123", "action": "created" }

Irizpro shows your error text to the site owner, so make it specific. After a failure the owner can publish again; your update-by-external_id rule keeps that safe.

Ready-made receivers

Each file verifies the signature, handles test deliveries, validates the payload and replies in the right format. You only implement the function that saves a post.

Go-live checklist

• ✓Endpoint is reachable over HTTPS (no redirect on POST).
• ✓Every request’s signature, timestamp and site_id are verified; anything else gets 401.
• ✓post.test deliveries return { "ok": true, "test": true } and are NEVER saved.
• ✓post.publish creates the post, or updates it when post.external_id already exists.
• ✓The reply is JSON: { "ok": true, "url": "<public URL of the post>", "id": "…", "action": "created" | "updated" }.
• ✓The post page has exactly one <h1> (the title) and shows the featured image once.
• ✓The page outputs <title>, meta description, canonical and og:title / og:description / og:image from the post fields.
• ✓The new post appears in the blog listing and the XML sitemap.
• ✓The Signing Secret is kept out of git (environment variable or a config file outside the web root).

“Send test” checks the first items automatically. After each real publish Irizpro also opens the live page and reports on the H1, featured image, meta tags, canonical and og:image.

Security

• Treat the Signing Secret like a password: environment variable or a config file outside the web root, never in git or front-end code.
• If it leaks, the site owner clicks New secret in Irizpro; the old one stops working at once. Update your server, then Send test.
• Sanitize HTML to your site’s rules if you allow only certain tags. Irizpro never sends scripts inside content_html.
• Your endpoint only needs to accept requests from Irizpro; the signature check is what enforces that.

FAQ

Irizpro Publish API v1 · spec value irizpro.publish.v1