Webhook Integration

EarlySEO generates article → POST to your endpoint → Your server processes it → Returns 2xx

{
  "event_type": "publish_articles",
  "timestamp": "2025-02-22T10:00:00.000Z",
  "data": {
    "articles": [
      {
        "id": "task_abc123",
        "title": "Best Practices for API Design",
        "slug": "api-design-best-practices",
        "meta_description": "Short SERP-optimized description...",
        "content_html": "<div class=\"earlyseo-article\"><style>...</style><h2>Introduction</h2><p>Styled HTML — works out of the box, colors overridable via CSS variables...</p></div>",
        "content_raw_html": "<h2>Introduction</h2><p>Bare HTML — no wrapper or styles...</p>",
        "content_css": ".earlyseo-article { color: var(--earlyseo-text-color, inherit); ... }",
        "content_markdown": "<h2>Introduction</h2><p>...</p>",
        "image_url": "https://cdn.example.com/featured.webp",
        "created_at": "2025-02-22T10:00:00.000Z",
        "tags": ["api", "design", "rest"]
      }
    ]
  },
  "id": "a1b2c3d4e5f6...",
  "type": "article.published",
  "created_at": "2025-02-22T10:00:00.000Z",
  "site": {
    "id": "site_xyz",
    "domain": "example.com"
  },
  "article": {
    "id": "task_abc123",
    "primary_keyword": "api design",
    "title": "Best Practices for API Design",
    "slug": "api-design-best-practices",
    "meta_description": "Short SERP-optimized description...",
    "html": "<h2>Introduction</h2><p>Clean HTML — inherits your site theme...</p>",
    "styled_html": "<div class=\"earlyseo-article\"><style>...</style><h2>Introduction</h2><p>...</p></div>",
    "featured_image": {
      "url": "https://cdn.example.com/featured.webp",
      "alt": "API design diagram"
    },
    "internal_links": [
      { "href": "/blog/rest-api-guide", "anchor": "REST API guide" }
    ],
    "summary": "A comprehensive guide to API design...",
    "keywords": ["api design", "rest api", "best practices"],
    "tags": ["api", "design", "rest"]
  },
  "meta": {
    "workspaceId": "ws_123",
    "integrationId": "int_456",
    "taskId": "task_abc123",
    "idempotencyKey": "a1b2c3d4e5f6..."
  }
}

// app/api/earlyseo-webhook/route.ts

export async function POST(req: Request) {
  // 1. Verify the Bearer token
  const authHeader = req.headers.get("authorization");
  if (authHeader !== `Bearer ${process.env.EARLYSEO_WEBHOOK_TOKEN}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  const body = await req.json();

  // 2. Handle test events (sent when you first create the integration)
  if (body.type === "integration.test") {
    return Response.json({ ok: true });
  }

  // 3. Extract article data
  const article = body.data?.articles?.[0];
  if (!article) {
    return new Response("No article in payload", { status: 400 });
  }

  // 4. Use the idempotency key to prevent duplicate processing
  const idempotencyKey = body.meta?.idempotencyKey;

  // 5. Save or publish the article
  // Example: save to your database
  await db.article.upsert({
    where: { externalId: idempotencyKey },
    create: {
      externalId: idempotencyKey,
      title: article.title,
      slug: article.slug,
      html: article.content_html,
      metaDescription: article.meta_description,
      imageUrl: article.image_url,
      tags: article.tags,
      publishedAt: new Date(),
    },
    update: {
      title: article.title,
      html: article.content_html,
      metaDescription: article.meta_description,
      imageUrl: article.image_url,
      tags: article.tags,
    },
  });

  // 6. Return 2xx — EarlySEO considers anything else a failure
  return Response.json({ ok: true });
}

EARLYSEO_WEBHOOK_TOKEN=your-secret-token-at-least-12-chars

import express from "express";

const app = express();
app.use(express.json());

app.post("/earlyseo-webhook", (req, res) => {
  // 1. Verify Bearer token
  const auth = req.headers.authorization;
  if (auth !== `Bearer ${process.env.EARLYSEO_WEBHOOK_TOKEN}`) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  // 2. Handle test events
  if (req.body.type === "integration.test") {
    return res.json({ ok: true });
  }

  // 3. Extract article
  const article = req.body.data?.articles?.[0];
  if (!article) {
    return res.status(400).json({ error: "No article" });
  }

  // 4. Process article (save, publish, enqueue, etc.)
  console.log("Received article:", article.title, article.slug);

  // 5. Return 200 quickly — do heavy processing in a background job
  res.json({ ok: true });
});

app.listen(3000);

from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route("/earlyseo-webhook", methods=["POST"])
def earlyseo_webhook():
    # 1. Verify Bearer token
    auth = request.headers.get("Authorization", "")
    expected = f"Bearer {os.environ['EARLYSEO_WEBHOOK_TOKEN']}"
    if auth != expected:
        return jsonify({"error": "Unauthorized"}), 401

    body = request.get_json()

    # 2. Handle test events
    if body.get("type") == "integration.test":
        return jsonify({"ok": True})

    # 3. Extract article
    articles = body.get("data", {}).get("articles", [])
    if not articles:
        return jsonify({"error": "No article"}), 400

    article = articles[0]

    # 4. Process article
    # save_article(article["title"], article["slug"], article["content_html"], ...)

    return jsonify({"ok": True})

import crypto from "crypto";

function verifySignature(rawBody: string, secret: string, signatureHeader: string): boolean {
  // signatureHeader looks like: "sha256=abcdef1234..."
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  // Use timingSafeEqual to prevent timing attacks
  if (expected.length !== signatureHeader.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Usage in your route handler:
const rawBody = await req.text(); // read body as string BEFORE parsing
const signature = req.headers.get("x-earlyseo-signature");

if (signature && !verifySignature(rawBody, process.env.EARLYSEO_HMAC_SECRET!, signature)) {
  return new Response("Invalid signature", { status: 403 });
}

const body = JSON.parse(rawBody);

import hmac
import hashlib

def verify_signature(raw_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

{
  "id": "your-internal-article-id",
  "url": "https://your-site.com/blog/article-slug",
  "externalId": "your-internal-article-id"
}