Host Your Blog on SEO Beast

Authentication

Response Format

{
  "success": true,
  "data": { /* response data */ },
  "meta": {
    "websiteSlug": "example-blog",
    "requestedAt": "2024-12-15T10:00:00Z",
    "version": "v1"
  }
}

{
  "success": false,
  "error": "Error message",
  "details": "Additional error details (if applicable)"
}

Endpoints

{
  "content": "Great article! Very helpful.",
  "author_name": "John Doe",
  "author_email": "john@example.com",
  "visitorId": "visitor_123",
  "parent_id": null  // Optional: UUID for reply comments
}

{
  "type": "like",           // "like" or "dislike"
  "visitorId": "visitor_123"
}

{
  "success": true,
  "data": {
    "message": "Reaction updated successfully",
    "comment": { /* updated comment with new like_count */ },
    "reaction": "like",      // Current reaction or null if removed
    "action": "added"        // "added", "updated", or "removed"
  }
}

Rate Limiting & Caching

Integration Examples

// Fetch latest posts
const response = await fetch('/v1/public/strong-curves/posts?limit=5');
const data = await response.json();

if (data.success) {
  // Process posts
  // data.data.posts
  // data.data.pagination.totalPages
}

// app/blog/[slug]/page.tsx
export const revalidate = 600; // re-fetch every 10 minutes

export default async function PostPage({ params }) {
  const { slug } = await params;
  const res = await fetch(
    `https://api.seobeast.io/v1/public/your-site/posts/${slug}`
  );
  const { data: post } = await res.json();

  return <article>{/* render post.title, post.content */}</article>;
}

---
// src/pages/blog/[slug].astro
const { slug } = Astro.params;
const res = await fetch(
  `${import.meta.env.API_BASE}/v1/public/your-site/posts/${slug}`
);
const { data: post } = await res.json();
---
<article>
  <h1>{post.title}</h1>
  <Fragment set:html={post.contentHtml} />
</article>

<!-- pages/blog/[slug].vue -->
<script setup>
const route = useRoute();
const { data } = await useFetch(
  `${useRuntimeConfig().public.apiBase}/v1/public/your-site/posts/${route.params.slug}`
);
const post = computed(() => data.value?.data);
</script>

<template>
  <article><h1>{{ post.title }}</h1></article>
</template>

// src/routes/blog/[slug]/+page.server.js
export async function load({ params, fetch }) {
  const res = await fetch(
    `https://api.seobeast.io/v1/public/your-site/posts/${params.slug}`
  );
  const { data: post } = await res.json();
  return { post };
}

import { useState, useEffect } from 'react';

function usePosts(websiteSlug, params = {}) {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    const fetchPosts = async () => {
      const searchParams = new URLSearchParams(params);
      const response = await fetch(`/v1/public/${websiteSlug}/posts?${searchParams}`);
      const data = await response.json();
      
      if (data.success) {
        setPosts(data.data.posts);
      }
      setLoading(false);
    };
    
    fetchPosts();
  }, [websiteSlug, params]);
  
  return { posts, loading };
}

Webhooks: instant cache updates

The read API is public and needs no key. Webhooks are the optional other half: SEO Beast calls your site the moment a post is published, updated, or deleted, so your cache clears instantly instead of waiting for a revalidation window. This is the only part of the integration that uses a secret.

Request signing

Every webhook POST carries an X-Webhook-Signature header: an HMAC-SHA256 of the raw request body, keyed with your secret. The body includes a timestamp field — verify the signature, then reject anything older than a few minutes to prevent replays.

Receiver (Next.js reference)

// app/api/webhooks/seobeast/route.ts
import crypto from "crypto";

export async function POST(request: Request) {
  const secret = process.env.SEOBEAST_WEBHOOK_SECRET!;
  const signature = request.headers.get("x-webhook-signature") ?? "";
  const rawBody = await request.text();

  // 1. Verify the HMAC signature (timing-safe)
  const expected = crypto.createHmac("sha256", secret)
    .update(rawBody).digest("hex");
  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return new Response("Invalid signature", { status: 401 });

  const payload = JSON.parse(rawBody);

  // 2. Replay protection: reject payloads older than 5 minutes.
  // payload.timestamp is inside the signed body, so it can't be forged.
  const sentAt = new Date(payload.timestamp).getTime();
  if (!Number.isFinite(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60_000) {
    return new Response("Stale webhook", { status: 401 });
  }

  // 3. Revalidate the affected content
  // e.g. revalidateTag("blog-posts"); revalidatePath(`/blog/${payload.data.slug}`)
  return new Response("ok");
}