Newsletter Webhook Integration Setup

Newsletter Webhook Integration Setup

This guide explains how to set up automatic newsletter notifications when new blog posts are published.

Overview

When a new blog post is published (pushed to the main branch), a GitHub Action automatically sends a notification to the newsletter API, which then emails all subscribers about the new post.

Prerequisites

• GitHub repository with Actions enabled
• Access to repository settings to add secrets
• Ruby installed locally for testing (optional but recommended)

Required Secrets and Configuration

GitHub Repository Secrets

The following secrets must be added to your GitHub repository:

API Endpoints

Setup Instructions

1. Add the Webhook Secret to GitHub

1. Go to your GitHub repository settings
2. Navigate to Settings → Secrets and variables → Actions
3. Click New repository secret
4. Add a new secret:
   • Name: NEWSLETTER_WEBHOOK_SECRET
   • Value: d9bd68f101c326057976e366c7c29ddfb3397abb2cbc01890488c6e9aeef0e2f
5. Click Add secret

2. Configure Repository Files

Ensure these files are present in your repository:

1. .github/workflows/notify-newsletter.yml - GitHub Actions workflow
2. .github/scripts/notify-new-posts.rb - Notification script
3. scripts/test-newsletter-webhook.rb - Testing script
4. .gitignore - Should include .github/notified-posts.json

3. Test the Integration

Before publishing a real post, test the webhook integration:

# Set the webhook secret as an environment variable
export NEWSLETTER_WEBHOOK_SECRET='d9bd68f101c326057976e366c7c29ddfb3397abb2cbc01890488c6e9aeef0e2f'

# Run the test script
ruby scripts/test-newsletter-webhook.rb

You should see output like:

✅ Success! Newsletter notification test passed.
   Your integration is working correctly.

4. Comprehensive Testing

For thorough testing before going live:

# Run the full test suite
./scripts/test-newsletter-integration.sh

# Simulate GitHub Actions locally
ruby scripts/simulate-github-action.rb

# Use the test workflow (push to test-newsletter-* branch)
git checkout -b test-newsletter-feature
git push origin test-newsletter-feature

See docs/NEWSLETTER_TESTING_GUIDE.md for detailed testing instructions.

5. How It Works

1. Trigger: When you push changes to _posts/*.md files on the main branch
2. Detection: The GitHub Action checks for new posts that haven’t been notified yet
3. Notification: For each new post, it sends a webhook request with:
   • Post title
   • Full URL to the post
   • Auto-generated excerpt (or manual excerpt if provided)
   • Author name (if available)
4. Tracking: Successfully notified posts are tracked in .github/notified-posts.json

6. Post Front Matter Options

You can control notifications using front matter in your posts:

---
title: "Your Post Title"
date: 2025-06-09
author: "Author Name"
excerpt: "Custom excerpt for the newsletter (optional)"
draft: true  # Set to true to prevent notification
published: false  # Set to false to prevent notification
---

7. Manual Testing

To manually test with a specific post:

1. Create a test post in _posts/
2. Push to a feature branch
3. Temporarily modify .github/workflows/notify-newsletter.yml to trigger on your branch
4. Push and check the Actions tab in GitHub

8. Monitoring

• Check GitHub Actions logs for notification status
• Successfully sent notifications show: ✅ Successfully notified newsletter subscribers
• Failed notifications show: ❌ Failed to notify subscribers (but won’t block deployment)
• The .github/notified-posts.json file tracks all notified posts

Troubleshooting

Notification Not Sending

1. Check GitHub Secret: Ensure NEWSLETTER_WEBHOOK_SECRET is set correctly
2. Check Post Status: Ensure post doesn’t have draft: true or published: false
3. Check GitHub Actions: Look at the workflow run logs for errors

Testing Locally

# Test with custom webhook URL (for local development)
ruby scripts/test-newsletter-webhook.rb --url http://localhost:3000/api/webhook/new-post --secret your-test-secret

Resending Notifications

If you need to resend a notification for a post:

1. Remove the post entry from .github/notified-posts.json
2. Push any change to trigger the workflow

API Documentation

Webhook Request Format

Headers:

Content-Type: application/json
x-webhook-secret: d9bd68f101c326057976e366c7c29ddfb3397abb2cbc01890488c6e9aeef0e2f

Request Body:

{
  "title": "Blog post title",
  "url": "https://blog.status.health/post-slug/",
  "excerpt": "Brief summary of the post (1-3 sentences)",
  "author": "Author name (optional)"
}

API Response Format

Success Response (200 OK):

{
  "success": true,
  "message": "Notification sent to X subscribers",
  "stats": {
    "total_subscribers": 100,
    "notifications_sent": 95,
    "notifications_failed": 5
  }
}

Error Response (401 Unauthorized):

{
  "error": "Invalid webhook secret"
}

Security Considerations

1. Never commit the webhook secret to code - Always use environment variables or GitHub Secrets
2. The webhook secret authenticates requests - Keep it secure and rotate if compromised
3. Failed notifications don’t block deployments - This prevents notification issues from breaking your blog
4. Tracking file is git-ignored - .github/notified-posts.json is not committed to avoid merge conflicts

Quick Reference

# Test webhook connectivity
export NEWSLETTER_WEBHOOK_SECRET='d9bd68f101c326057976e366c7c29ddfb3397abb2cbc01890488c6e9aeef0e2f'
ruby scripts/test-newsletter-webhook.rb

# Run full test suite
./scripts/test-newsletter-integration.sh

# Check GitHub Actions logs
# Go to: Actions tab → "Notify Newsletter Subscribers" workflow

# View tracking file (after notifications sent)
cat .github/notified-posts.json