Webhook API Reference

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

I use SEOGrove (seogrove.io) to auto-generate and publish SEO articles to my site via webhook. Please implement a complete webhook receiver so my site can receive and display these articles.

## 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
  User-Agent: SEOGrove/1.0

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
    "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": []
  }
}

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. Fields to save
   title, slug, html body, excerpt, seo_title, meta_description,
   featured_image_url, featured_image_alt, published_at

4. 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.

5. Return 200 OK for all successfully processed events.

## 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"]
      )
    end

    render json: { received: true }
  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