Blog Webhooks: Automate What Happens When You Publish

Publishing a post is rarely the last step. Someone shares it, a cache needs clearing, a static mirror needs rebuilding, a team chat wants to know. Doing that by hand works until you forget. Webhooks let the blog do it for you: the moment something changes, it sends a request to whichever service needs to know.

What a webhook is

A webhook is a push notification between servers. When an event happens, such as a post being published, the blog sends an HTTP POST with a small JSON description of what changed to an address you choose. It is the opposite of polling: an RSS feed waits for readers and tools to come and check, while a webhook tells them straight away.

What to automate

Start with one hook that saves you a manual step every time you publish, and add more once it has proven reliable:

• Rebuild a site. Trigger a deploy hook so a static mirror or docs site picks up the new post. If you are weighing that kind of setup, see our guide to a static site CMS.
• Post to social or chat. Send new posts to an automation service that shares them, or to a team channel.
• Purge a cache. Clear a CDN or reverse-proxy cache when a post is updated, so readers see the new version.
• Alert moderators. Notify someone when a reader leaves a comment that is waiting for approval.

Making deliveries reliable

The receiving service will sometimes be slow or down. A good webhook system plans for that:

• Queue, do not block. Sending should never hold up the publish button.
• Retry with backoff. Try again after increasing delays before giving up.
• Make retries safe. Give every delivery a stable id so the receiver can ignore duplicates.
• Keep a log. Record each attempt and its response, and allow a manual redelivery.

Making webhooks secure

Anyone who knows your receiver's address can send it a request, so the receiver must check that each one is genuine. The standard approach is an HMAC signature: the blog signs the timestamp and body with a shared secret, and the receiver recomputes it. Checking the timestamp also stops an old delivery from being replayed. Here is a receiver check in Node.js for a header in the form t=<unix>,v1=<hex>:

const crypto = require('crypto');

function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  return parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Verify against the raw request body, before any JSON parsing changes it. Then reply quickly with a 2xx status and do the slow work afterwards: a receiver that takes too long looks like a failure to the sender and triggers a retry.

There is a risk on the sending side too. If a webhook can point at any address, the blog can be tricked into calling services on its own private network, a problem known as server-side request forgery. A careful sender refuses private and local addresses, does not follow redirects, and keeps personal data such as commenter email addresses out of the payload.

How Inkwell webhooks work

Since v1.0.8, Admin > Webhooks sends a signed JSON request when a post is published (including a scheduled post reaching its time), updated or unpublished, when a page is published, or when a reader submits a comment.

• Delivery: queued and sent by the scheduler within a minute, never on the publish request. Failures are retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then marked failed.
• Log: 30 days per endpoint, with the response code, Redeliver and Send test.
• Headers:X-Inkwell-Event, a stable X-Inkwell-Delivery id that a redelivery keeps, and X-Inkwell-Signature in the format above, an HMAC-SHA256 of the timestamp and body.
• Safety: the signing secret is generated for you, stored encrypted and never shown again. Addresses on the server itself or a private network are refused, and payloads never include a commenter's email address or IP.
• Access: Admin-only, and every change, test and redelivery is audited.

Configuration and setup are covered in the documentation.

• #Publishing
• #Automation
• #Developer Tools
• #Security