ghost-webhooks

Ghost Webhooks & Integrations

Overview

Ghost webhooks send a POST request to a target URL when content or member events occur. There are 31 events across four categories. Webhooks can be created via the Ghost Admin UI or the Admin API.

Prerequisite: For API-managed webhooks, authentication configured — see ghost-admin-api-auth.

Announce at start: "I'm using the ghost-webhooks skill."

---

Creating Webhooks

Via Ghost Admin (UI)

Settings → Advanced → Integrations → Add custom integration → Add webhook.

Via Admin API

curl -X POST \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v5.0" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [{
      "event": "post.published",
      "target_url": "https://yourserver.com/hooks/ghost",
      "name": "Notify on publish",
      "secret": "your_webhook_secret"
    }]
  }' \
  "$GHOST_ADMIN_URL/ghost/api/admin/webhooks/"

Update a Webhook

curl -X PUT \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v5.0" \
  -H "Content-Type: application/json" \
  -d '{"webhooks": [{"target_url": "https://newurl.com/hooks/ghost"}]}' \
  "$GHOST_ADMIN_URL/ghost/api/admin/webhooks/{WEBHOOK_ID}/"

Delete a Webhook

curl -X DELETE \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v5.0" \
  "$GHOST_ADMIN_URL/ghost/api/admin/webhooks/{WEBHOOK_ID}/"

---

All 31 Webhook Events

Site

Event	Triggers on
site.changed	Any content or settings change

Post Events (11)

Event	Triggers on
post.added	New post created (any status)
post.edited	Post content or settings changed
post.deleted	Post deleted
post.published	Post status changed to published
post.published.edited	Published post content edited
post.unpublished	Published post reverted to draft
post.scheduled	Post scheduled for future publish
post.unscheduled	Scheduled post moved back to draft
post.scheduled.cancelled	Scheduled post deleted before publishing
post.tag.attached	Tag added to a post
post.tag.detached	Tag removed from a post

Page Events (same pattern as posts, 5 events)

Event
page.added
page.edited
page.deleted
page.published
page.unpublished
page.tag.attached
page.tag.detached

Tag Events (3)

Event
tag.added
tag.edited
tag.deleted

Member Events (3)

Event
member.added
member.edited
member.deleted

---

Webhook Payload

Ghost sends a POST with Content-Type: application/json. The body structure is:

{
  "post": {
    "current": {
      "id": "abc123",
      "title": "My Post",
      "status": "published",
      "published_at": "2024-08-01T10:00:00.000Z",
      "url": "https://example.com/my-post/",
      "authors": [...],
      "tags": [...]
    },
    "previous": {
      "status": "draft"
    }
  }
}

The top-level key matches the resource type (post, page, tag, member). current is the current state; previous contains only changed fields.

---

Verifying Webhook Signatures

If you set a secret when creating the webhook, Ghost signs each payload with HMAC-SHA256.

Signature is in the X-Ghost-Signature header:

X-Ghost-Signature: sha256=abc123..., t=1722513600

Node.js verification:

import crypto from 'crypto';

function verifyGhostWebhook(secret, rawBody, signatureHeader) {
  const [sigPart, tPart] = signatureHeader.split(', ');
  const receivedSig = sigPart.replace('sha256=', '');
  const timestamp = tPart.replace('t=', '');

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedSig),
    Buffer.from(expectedSig)
  );
}

Always verify before processing. Return 200 regardless (prevents retry loops).

---

Delivery & Retries

• Ghost expects a 2xx response within a reasonable timeout
• Failed deliveries are retried — make your handler idempotent
• Target URL must be internet-accessible (not localhost) in production

---

Local Development with ngrok

For local webhook testing, expose your local server:

# Install ngrok
npm install -g ngrok

# Expose local port 3000
ngrok http 3000

Use the generated https://xxxxx.ngrok.io URL as your webhook target. Update it in Ghost Admin each session.

---

Stripe Webhook Local Dev

Ghost uses Stripe webhooks internally for subscription events. For local dev:

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward Stripe webhooks to your local Ghost instance
stripe listen --forward-to http://localhost:2368/members/webhooks/stripe/

---

Common Integration Patterns

Trigger a site rebuild on publish (Jamstack)

// Express.js handler
app.post('/hooks/ghost', express.json(), async (req, res) => {
  res.sendStatus(200); // Acknowledge immediately
  if (req.body?.post?.current?.status === 'published') {
    await triggerNetlifyBuild(); // or Vercel, Cloudflare Pages, etc.
  }
});

Sync new members to a CRM

app.post('/hooks/ghost/member-added', express.json(), async (req, res) => {
  res.sendStatus(200);
  const member = req.body?.member?.current;
  if (member) {
    await syncToCRM({ email: member.email, name: member.name });
  }
});

Post to Slack on publish

app.post('/hooks/ghost/published', express.json(), async (req, res) => {
  res.sendStatus(200);
  const post = req.body?.post?.current;
  if (post?.status === 'published') {
    await fetch(SLACK_WEBHOOK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: `New post: ${post.title} — ${post.url}` }),
    });
  }
});

---

Checklist

• Webhook target URL is internet-accessible (not localhost) in production
• secret set on webhook for signature verification
• Handler returns 200 immediately (before async processing)
• Handler is idempotent (safe to receive duplicate deliveries)
• X-Ghost-Signature verified before processing payload
• For local dev: ngrok running and URL updated in Ghost Admin
• For Stripe local dev: Stripe CLI forwarding to /members/webhooks/stripe/