Webhook API Reference

{
  "event": "ping",
  "timestamp": "2026-05-01T10:00:00Z"
}

I use SEOGrove (seogrove.io) to auto-generate, publish, and prune SEO articles and free tools on my site via webhook. Please implement a complete webhook receiver so my site can receive, display, update, and delete articles and tools.

## What SEOGrove sends

POST to my webhook URL with these headers:
  Content-Type: application/json
  X-SEOGrove-Signature: sha256=<hmac-hex>   (HMAC-SHA256 of the raw request body)
  X-SEOGrove-Event: content.published, tool.published, content.deleted, tool.deleted, or ping
  User-Agent: SEOGrove/1.0

Publish payload structure:
{
  "event": "content.published",
  "timestamp": "2026-05-01T10:00:00Z",
  "site": { "host": "yoursite.com", "url": "https://yoursite.com", "locale": "en" },
  "content": {
    "id": 42,
    "title": "Article Title",
    "slug": "article-slug",           <-- use as upsert key to avoid duplicates on re-publish
    "locale": "en",
    "canonical_path": "/article-slug", <-- tools use /tools/:slug
    "external_id": null,
    "external_url": null,
    "html": "<p>Body HTML...</p>",    <-- semantic unstyled HTML; no H1, image, or schema
    "markdown": "Body markdown...",
    "schema_json": { "@context": "https://schema.org", "@type": "BlogPosting", "inLanguage": "en" },
    "excerpt": "First paragraph, max 300 chars",
    "featured_image_url": "https://cdn.seogrove.io/image.png",  <-- null if no image; NOT in html body
    "featured_image_alt": "Descriptive alt text — primary keyword",
    "content_type": "article",
    "published_at": "2026-05-01T10:00:00Z",
    "word_count": 1500,
    "primary_keyword": "target keyword",
    "seo_title": "SEO-optimised title variant",   <-- use as <title> tag if present
    "meta_description": "150-160 char description",
    "category": "Permits",
    "tags": []
  }
}

For "tool.published", content.content_type is "mini_tool", content.canonical_path should be used as the page path, and content.html contains the native tool page body. Store tools separately from blog posts if your app has a separate Tool/Page model; otherwise create a page at /tools/:slug. Receivers should store the signed native tool artifact from content.tool.native_html and render it as trusted first-party HTML, or render content.tool.manifest with their own component. Use content.tool.iframe_fallback only for locked-down CMSs that cannot run native tool assets.

Delete payload structure:
{
  "event": "content.deleted",
  "timestamp": "2026-05-01T10:00:00Z",
  "site": { "host": "yoursite.com", "url": "https://yoursite.com", "locale": "en" },
  "content": {
    "id": 42,
    "title": "Article Title",
    "slug": "article-slug",
    "locale": "en",
    "external_id": null,
    "external_url": "https://example.com/blog/article-slug"
  }
}

SEOGrove also sends a lightweight ping to verify the connection:
{ "event": "ping", "timestamp": "..." }
Respond 200 immediately — no signature check needed for pings.

## Requirements

1. Signature verification
   - Read the raw request body BEFORE parsing JSON (parsing can alter whitespace and break the sig)
   - Compute: expected = "sha256=" + HMAC-SHA256(SEOGROVE_WEBHOOK_SECRET env var, raw_body)
   - Use a timing-safe comparison to prevent timing attacks
   - Return 401 if invalid

2. Upsert logic
   - Use slug as the unique key: find_or_initialize_by(slug: ...) so re-publishing updates the existing record

3. Delete logic
   - If event == "content.deleted", find the article by slug and delete it or unpublish it
   - If your system stores external IDs or canonical URLs, also support lookup by external_id or external_url
   - Deletes must be idempotent: if the article is already missing, still return 200 OK

4. Fields to save
   title, slug, html body, schema_json, excerpt, seo_title, meta_description,
   featured_image_url, featured_image_alt, published_at

5. Page template requirements
   - Render title as the <h1> — the html body does NOT include one
   - <title> tag: use seo_title if present, otherwise title
   - <meta name="description">: use meta_description
   - Display featured image ABOVE the article body:
       <img src="{{ featured_image_url }}" alt="{{ featured_image_alt }}">
     Only render the image block if featured_image_url is present.
   - Render schema_json separately as JSON-LD:
       <script type="application/ld+json">{{ schema_json_as_json }}</script>
   - Apply your own article CSS for headings, paragraphs, lists, tables, links, images, and blockquotes. SEOGrove does not send presentation classes in article HTML so it works across Rails, WordPress, Webflow, static sites, and custom CMS receivers.

6. Return 200 OK for all successfully processed events.
   - Include the final published URL when available:
     { "received": true, "url": "https://example.com/blog/article-slug" }
   - For deletes, return:
     { "received": true, "deleted": true }

## My tech stack
[DESCRIBE YOUR STACK HERE — e.g. "Ruby on Rails 8 with PostgreSQL", "Next.js 14 with Prisma", "Laravel 11", "Django 5 with SQLite", etc.]

# app/controllers/hooks_controller.rb
class HooksController < ActionController::Base
  skip_before_action :verify_authenticity_token

  def seogrove
    raw_body = request.body.read
    payload  = JSON.parse(raw_body)
    event    = payload["event"]

    # Always respond 200 to pings immediately
    if event == "ping"
      render json: { received: true } and return
    end

    unless valid_signature?(raw_body)
      render json: { error: "Invalid signature" }, status: :unauthorized and return
    end

    if event == "content.published"
      content = payload["content"]
      post = Post.find_or_initialize_by(slug: content["slug"])
      post.update!(
        title:              content["title"],
        body:               content["html"],
        excerpt:            content["excerpt"],
        seo_title:          content["seo_title"],
        meta_description:   content["meta_description"],
        featured_image_url: content["featured_image_url"],
        featured_image_alt: content["featured_image_alt"],
        published_at:       content["published_at"]
      )
      render json: { received: true, url: post_url(post) } and return
    elsif event == "tool.published"
      content = payload["content"]
      tool = ToolPage.find_or_initialize_by(slug: content["slug"])
      tool.update!(
        title: content["title"],
        path: content["canonical_path"],
        body: content["html"],
        tool_payload: content["tool"],
        published_at: content["published_at"]
      )
      render json: { received: true, url: tool_url(tool) } and return
    elsif event == "content.deleted" || event == "tool.deleted"
      content = payload["content"]
      post = Post.find_by(slug: content["slug"])
      deleted = post.present?
      post&.destroy!
      render json: { received: true, deleted: deleted } and return
    end

    render json: { error: "Unsupported event" }, status: :unprocessable_entity
  rescue JSON::ParserError
    render json: { error: "Invalid JSON" }, status: :unprocessable_entity
  end

  private

  def valid_signature?(raw_body)
    secret   = Rails.application.credentials.dig(:seogrove, :webhook_secret)
    expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
    ActiveSupport::SecurityUtils.secure_compare(expected,
      request.headers["X-SEOGrove-Signature"].to_s)
  end
end