Custom API (webhook)

I need to create a webhook endpoint that receives blog articles from Rankealo and saves them to my site. Please create a POST route.

## Authentication
Rankealo sends the header `Authorization: Bearer <access token>`. Store the token in the env var `RANKEALO_WEBHOOK_TOKEN` and reject requests (401) unless `request.headers.get('authorization') === `Bearer ${process.env.RANKEALO_WEBHOOK_TOKEN}``.

## Connection test
Rankealo sends an empty JSON body `{}` when the user clicks "Test connection". Return 200 JSON `{ "ok": true }`.

## Events (POST, JSON)
All events look like `{ event_type, timestamp, data: { articles: [...] } }`.

1. `publish_articles` - create the post. Article fields: id, title, slug, content_markdown, content_html, meta_description, image_url, tags, created_at, article_schema, faq_schema, open_graph.
```json
{
  "event_type": "publish_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": {
    "articles": [{
      "id": "uuid",
      "title": "Article title",
      "slug": "article-title-1a2b3c",
      "content_markdown": "# Heading\n\nBody...",
      "content_html": "<div class=\"rankealo-content\">...</div>",
      "meta_description": "SEO description",
      "image_url": "https://.../featured.jpg",
      "tags": [],
      "created_at": "2026-01-15T11:58:00.000Z",
      "article_schema": { "@type": "Article" },
      "faq_schema": null,
      "open_graph": { "og:title": "..." }
    }]
  }
}
```
UPSERT keyed on the article `id` (never on slug alone; slug is a mutable attribute that may change between publish and update; enforce a UNIQUE constraint on id and handle slug collisions with a suffix). Respond 200 with `{ "ok": true, "id": "<article id>", "url": "<live article url>" }` (always return id so Rankealo can address later updates).

2. `update_articles` - same content fields as publish, plus `cms_post_id`. Treat it exactly like publish: UPSERT by article `id`. Respond 200 `{ "ok": true, "id": "<article id>" }`.
```json
{
  "event_type": "update_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": {
    "articles": [{
      "id": "uuid",
      "cms_post_id": "the id you returned on publish (or the article id)",
      "title": "Updated title",
      "content_markdown": "...",
      "content_html": "...",
      "meta_description": "...",
      "article_schema": null,
      "faq_schema": null,
      "open_graph": {}
    }]
  }
}
```

3. `delete_articles` - delete the post by article id; a no-op if it is missing. Respond 200 `{ "ok": true }`.
```json
{
  "event_type": "delete_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": { "articles": [{ "id": "uuid" }] }
}
```

Unknown event_type: return 400. Respond 200 JSON promptly and do heavy work after responding.

## Handling retries
Respond 2xx only after the article is durably saved. A non-2xx response or a timeout means Rankealo may send the same event again, so handlers must be idempotent (processing the same event twice yields the same state). Rankealo waits up to 2 minutes for publish/update responses and 30 seconds for delete and the connection test, so respond quickly and do heavy work after responding. If the publish response has no id, Rankealo uses the payload's article id as the post id. Each request also carries `X-Rankealo-Delivery-Id`, which stays the same when the same delivery is re-sent (optional dedupe).

Any non-2xx response is treated as a failure. Please detect my framework (Next.js, Express, etc.), create the route in the right place, add the env var to my .env, and save articles into my existing blog/CMS if possible. Prefer `content_markdown`; use `content_html` only if I render HTML directly.

// app/api/rankealo/route.ts
// .env: RANKEALO_WEBHOOK_TOKEN=<the access token you generated in Rankealo>
//
// Storage rules (replace db.* with your own database calls):
//  - Key everything on article.id. Add a UNIQUE constraint on it, e.g.
//      CREATE TABLE posts (id text PRIMARY KEY, slug text, title text, ...);
//  - slug is a mutable attribute, never the key: it can change between
//    publish and update. TODO: keep slug unique by appending a suffix on conflict.
//  - Handlers must be idempotent: the same event twice leaves the same state.

async function upsertPost(article: any) {
  // publish_articles AND update_articles: insert-or-update WHERE id = article.id
  await db.posts.upsert({
    where: { id: article.id },
    data: {
      slug: article.slug, // may change between publish and update
      title: article.title,
      contentMarkdown: article.content_markdown,
      contentHtml: article.content_html,
      metaDescription: article.meta_description,
      imageUrl: article.image_url,
    },
  });
}

export async function POST(request: Request) {
  // Rankealo sends: Authorization: Bearer <your access token>
  const expected = `Bearer ${process.env.RANKEALO_WEBHOOK_TOKEN}`;
  if (request.headers.get('authorization') !== expected) {
    return Response.json({ ok: false, error: 'Unauthorized' }, { status: 401 });
  }

  // Connection test sends an empty JSON body {}
  const body = await request.json().catch(() => ({}));
  if (!body.event_type) return Response.json({ ok: true });

  // Optional: X-Rankealo-Delivery-Id is identical when Rankealo re-sends the
  // same delivery. Log/dedupe on it if you like; upserting by id is enough.
  const articles = body.data?.articles ?? [];

  // Respond promptly: do heavy work (revalidation, search indexing, image
  // processing) after the response, e.g. with after() or a queue.
  switch (body.event_type) {
    case 'publish_articles':
    case 'update_articles': {
      for (const article of articles) await upsertPost(article);
      const first = articles[0];
      // Always return the id so Rankealo can address later updates.
      return Response.json({
        ok: true,
        id: first?.id,
        url: first ? `https://your-site.com/blog/${first.slug}` : undefined,
      });
    }

    case 'delete_articles':
      // Delete by id; deleting something that is already gone is a no-op.
      for (const article of articles) await db.posts.deleteMany({ where: { id: article.id } });
      return Response.json({ ok: true });

    default:
      return Response.json({ ok: false, error: 'Unknown event_type' }, { status: 400 });
  }
}

{ "ok": true }

{
  "event_type": "publish_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": {
    "articles": [{
      "id": "uuid",
      "title": "Article title",
      "slug": "article-title-1a2b3c",
      "content_markdown": "# Heading\n\nBody...",
      "content_html": "<div class=\"rankealo-content\">...</div>",
      "meta_description": "SEO description",
      "image_url": "https://.../featured.jpg",
      "tags": [],
      "created_at": "2026-01-15T11:58:00.000Z",
      "article_schema": { "@type": "Article" },
      "faq_schema": null,
      "open_graph": { "og:title": "..." }
    }]
  }
}

{
  "event_type": "update_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": {
    "articles": [{
      "id": "uuid",
      "cms_post_id": "the id you returned on publish (or the article id)",
      "title": "Updated title",
      "content_markdown": "...",
      "content_html": "...",
      "meta_description": "...",
      "article_schema": null,
      "faq_schema": null,
      "open_graph": {}
    }]
  }
}

{
  "event_type": "delete_articles",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "data": { "articles": [{ "id": "uuid" }] }
}