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" },
  "content": {
    "id": 42,
    "title": "Article Title",
    "slug": "article-slug",           <-- use as upsert key to avoid duplicates on re-publish
    "canonical_path": "/article-slug", <-- tools use /tools/:slug
    "external_id": null,
    "external_url": null,
    "html": "<p>Body HTML...</p>",    <-- no H1 tag; your template renders the title as H1
    "markdown": "Body markdown...",
    "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",
    "tags": []
  }
}

For "tool.published", content.content_type is "mini_tool", content.canonical_path should be used as the page path, and content.tool.embed_code contains an iframe fallback. Store tools separately from blog posts if your app has a separate Tool/Page model; otherwise create a page at /tools/:slug.

Delete payload structure:
{
  "event": "content.deleted",
  "timestamp": "2026-05-01T10:00:00Z",
  "site": { "host": "yoursite.com", "url": "https://yoursite.com" },
  "content": {
    "id": 42,
    "title": "Article Title",
    "slug": "article-slug",
    "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, 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.

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