AGENTS

Hook Mesh Blog Guidelines

This document defines the content strategy, tone, and technical requirements for all Hook Mesh blog posts.

Brand Positioning

Hook Mesh is a webhook delivery service targeting SMB SaaS companies (seed to Series B).

Tagline: "Webhooks that just work"

Key differentiators:

• Startup-friendly pricing ($0-249/mo vs competitors at $490+/mo)
• Simplicity over enterprise feature bloat
• Fast time-to-value
• No infrastructure to maintain

We are NOT competing for:

• Enterprise accounts requiring SOC 2 Type II, HIPAA (yet)
• Self-hosted/open-source users
• Inbound webhook processing (we focus on outbound delivery)

Content Strategy

Pillar Pages (6)

These are comprehensive hub pages that link out to related content:

Content Categories

1. Foundational - "What are webhooks", comparisons, industry trends
2. Startup-focused - MVP, scaling, mistakes, pricing (our unique angle)
3. Language tutorials - Node.js, Python, Go (send + receive)
4. Framework guides - Next.js, Django, Express, Serverless
5. Platform integrations - Stripe, Shopify, GitHub, Twilio, etc.
6. Technical deep-dives - Idempotency, circuit breakers, observability
7. Security - HMAC, SSRF, auth methods, checklists
8. Comparisons - Hook Mesh vs Svix, Hook Mesh vs Hookdeck

SEO Strategy

High-value keywords we target:

• "what are webhooks" (educational, high volume)
• "webhook security" (intent signal)
• "[platform] webhooks" (long-tail, high intent)
• "svix alternative" / "hookdeck alternative" (competitor capture)
• "webhooks for startups" (our unique positioning)

Content gaps we exploit:

• Startup-specific content (no competitor owns this)
• Cost/pricing transparency
• Security deep-dives beyond basics
• Debugging and observability guides

Tone and Voice

Do

• Be direct and practical - developers value clarity
• Use second person ("you") to speak directly to readers
• Include working code examples in every technical post
• Be honest about trade-offs - don't oversell Hook Mesh
• Acknowledge competitor strengths in comparison posts
• Use concrete examples over abstract explanations

Don't

• Use marketing fluff or buzzwords
• Be salesy or pushy about Hook Mesh
• Oversimplify to the point of being unhelpful
• Use excessive exclamation points or hype language
• Add unnecessary emojis
• Pad content to hit word counts

Hook Mesh Mentions

• 1-2 natural mentions per post - never forced
• Best placements: reliability section, conclusion CTA
• Frame as "here's how Hook Mesh handles this" not "buy Hook Mesh"
• Always provide value even if reader doesn't use Hook Mesh

Writing Tight, Value-Packed Prose

Hook Mesh blog content prioritizes density over length. Every sentence must earn its place. Target a 15-20% reduction in typical blog post word count through ruthless elimination of filler while preserving all technical depth.

Cut This (Filler That Adds No Value):

Transition padding:

• "Before integrating webhooks into your production application, you need a safe environment to experiment..."
• "As you grow, you'll encounter customers with flaky endpoints..."
• "The question isn't whether you need webhooks—it's when..."
• Replace with: Direct statements that skip the obvious setup.

Redundant explanations:

• "Webhooks are automated messages sent from one application to another when a specific event occurs. Think of them as a notification system between servers." (both sentences say the same thing)
• Replace with: "Webhooks are automated messages sent when events occur—a push model instead of constant polling."

Filler phrases:

• "This is perfect for", "Fortunately", "one thing... entirely different"
• "Here is", "It is", "The fact that"
• "At their core", "In essence", "Basically"
• Future-tense filler: "you will", "you can", "you'll"
• "The good news is", "This sounds straightforward, but"
• Replace with: Direct, active voice.

Section intros that restate the header:

• Header: "## Production Security Checklist"
• Content: "Moving from development to production requires systematic validation of your webhook security implementation."
• Replace with: Delete the intro, jump straight to the checklist.

Verbose lead-ins before content:

• "Before diving into code, consider what you're building:" (obvious)
• "These guides dive deep into framework conventions, making webhooks feel native to your stack." (marketing fluff)
• Replace with: Just list the guides.

Marketing adjectives that weaken meaning:

• "essential", "mission-critical", "comprehensive", "battle-tested", "significantly impacts"
• Replace with: Concrete specifics. Instead of "essential infrastructure", say "handles 100+ billion webhooks annually."

Explanatory sentences that don't add value:

• "Understanding when to use webhooks versus traditional APIs is fundamental to building efficient integrations." (obvious from section title)
• "This is perfect for understanding the exact format of webhook payloads before writing any code." (self-evident)
• Replace with: Delete and move to next sentence.

Keep This (Value-Dense Content):

✓ All code examples and technical patterns ✓ Concrete scenarios and attack examples ✓ Specific numbers: "6-12 months to build", "10-second timeout", "5 retries" ✓ Real platform names (Stripe, GitHub, Shopify, not "providers") ✓ Tables, frameworks, and checklists ✓ Error handling and edge cases ✓ Why something matters (with concrete consequences) ✓ Real case studies or examples

Examples of Good Edits:

Before (112 words):

Webhooks have become essential infrastructure for modern applications. They power payment notifications, CI/CD pipelines, real-time collaboration tools, and countless other integrations. The concepts are straightforward, but building production-ready webhook infrastructure requires attention to security, reliability, and scale. This comprehensive guide covers everything you need to know about building webhook infrastructure that your team and customers can depend on.

After (48 words):

Webhooks power payment notifications, CI/CD pipelines, and real-time integrations. Building production-ready infrastructure requires attention to security, reliability, and scale. This guide covers everything you need.

Before (85 words):

Before integrating webhooks into your production application, you need a safe environment to experiment and understand how they work. Fortunately, several free tools make this easy. When you are ready to test your actual webhook handler code, ngrok bridges the gap between webhook providers and your local machine.

After (32 words):

Use these free tools to test safely:

• ngrok: Exposes your local server to webhook providers with a public URL
• webhook.site: Instantly captures incoming webhooks for inspection

Before (95 words):

Node.js is a natural fit for webhook handling thanks to its event-driven architecture. Our tutorial covers payload structure, HMAC signatures, error handling, and retry logic using modern ES modules and the native fetch API. Best for: Teams already using Node.js, real-time applications, startups moving fast.

After (35 words):

Node.js: Production-ready delivery with async queuing, HMAC signatures, exponential backoff, TypeScript support. Best for: Real-time apps, startups.

Pillar Page Specifics:

Pillar pages are navigation hubs. They should be even tighter than regular posts:

• Remove "What You Will Learn" sections (redundant with TOC)
• Delete intro sentences explaining what the section title already conveys
• Convert verbose platform descriptions into single-line summaries with key topics
• Replace "Learn to..." intros with just the link: [Send Webhooks with Node.js](./link)

Self-Editing Checklist:

Before shipping, scan for:

• Any sentence starting with "This is", "Here is", "At their core", "In essence" → cut or rewrite
• Any paragraph intro that restates the header → delete
• Any explanation of something obvious from context → cut
• Filler phrases: "take time to", "the fact that", "the question is" → remove
• Marketing adjectives without specifics → replace with concrete numbers
• Sentences longer than 20 words → consider breaking into two or cutting
• Any "you will", "you can", "you'll" future tense filler → use present tense or imperative

Post Structure

Frontmatter (Required)

---
title: "Post Title Here"
description: "SEO-friendly description, 150-160 characters"
author: "Hook Mesh Team"
publishedAt: "2026-01-20"
updatedAt: "2026-01-20"
category: "security" | "reliability" | "tutorial" | "integration" | "startup" | "comparison" | "fundamentals"
tags:
  - webhooks
  - relevant-tag
keywords:
  - target keyword
  - secondary keyword
relatedPosts:
  - post-slug-1
  - post-slug-2
  - post-slug-3
---

relatedPosts Guidelines

Only include posts that are extremely relevant:

• Same topic cluster (e.g., security posts link to security posts)
• Natural "read next" progression
• Complementary content (e.g., "send" links to "receive")
• 3-5 posts maximum

Good examples:

• webhook-retry-strategies → webhook-circuit-breakers (same reliability cluster)
• send-webhooks-nodejs → receive-verify-webhooks-nodejs (complementary)
• webhooks-for-startups → mvp-webhook-architecture (natural progression)

Bad examples:

• webhook-security-best-practices → shopify-webhooks-complete-guide (weak connection)
• Linking to every post mentioning "webhooks" (too broad)

Body Structure

1. Introduction (2-3 paragraphs)

   • Hook the reader with a problem or scenario
   • State what they'll learn
   • No "In this post, we'll cover..." - just get to it

2. Main Content (organized with H2/H3 headers)

   • Each major section: H2
   • Subsections: H3
   • Include code examples where relevant
   • Use tables for comparisons
   • Use bullet lists for scannable content

3. Conclusion (1-2 paragraphs)

   • Summarize key takeaways
   • Include CTA (Hook Mesh signup, docs, or related content)

Code Examples

• Use fenced code blocks with language hints: javascript, python, ```go
• Keep examples complete and runnable when possible
• Include error handling in production examples
• Show both "wrong" and "right" approaches when teaching
• For SDK examples, use @hookmesh/node, hookmesh (Python), hookmesh-go

Internal Linking

Inline Links

Add contextual inline links where they provide value:

Good:

Before sending webhooks, you need to understand HMAC signature verification to ensure security.

Bad:

Learn more about webhooks and security and retries.

Link Anchor Text

Use descriptive anchor text, not "click here" or "learn more":

Pillar Page Links

Every post should link to its relevant pillar page at least once:

• Security posts → pillar-webhook-security-guide.md
• Reliability posts → pillar-webhook-reliability-engineering.md
• Startup posts → pillar-webhooks-for-startups.md
• Platform posts → pillar-platform-integrations.md
• Language/framework posts → pillar-webhook-implementation-guides.md

File Naming

Use kebab-case slugs that match the URL:

Pillar pages use pillar- prefix:

Content Inventory

By Category

Crosslink Strategy

See CROSSLINK_STRATEGY.md for the complete linking map.

Quality Checklist

Before publishing, verify:

• Frontmatter complete (title, description, category, tags, relatedPosts)
• Target keyword appears in title and first paragraph
• At least one code example (for technical posts)
• 3-5 inline links to related content
• Link to relevant pillar page
• Hook Mesh mention is natural, not forced
• No broken internal links
• Proper markdown formatting (headers, code blocks, lists)
• Tight prose: No filler phrases, redundant explanations, or marketing adjectives
• Self-editing checklist applied (see "Writing Tight, Value-Packed Prose" section)
• Target ~15-20% less than typical blog length while maintaining technical depth
• 800-2000 words (compress to value density, not word count)

Updating Posts

When updating existing posts:

1. Update updatedAt in frontmatter
2. Keep original publishedAt date
3. Add new inline links if relevant content has been published
4. Update relatedPosts if better matches exist
5. Don't change URLs/slugs (breaks external links)

Revision History

2026-01-20

• Added "Writing Tight, Value-Packed Prose" section with specific guidance on eliminating filler
• Added self-editing checklist for tight prose
• Updated Quality Checklist to emphasize value density over word count
• Result: Apply across all 6 pillar posts, achieving 15-27% word reduction while preserving technical depth

Last updated: 2026-01-20