Events & webhooks

Events are Buttondown's way of telling you that something interesting has happened to your newsletter, and webhooks are Buttondown's way of letting you react to various incoming events. For example, when a new subscriber signs up for your newsletter, Buttondown creates and emits a subscriber.created event; when that subscriber unsubscribes, Buttondown creates a subscriber.unsubscribed event. If you wanted to, say, create a Slack notification or run some application code whenever something in Buttondown happens, you'd create a webhook for the concomitant event and point it towards your application.

The payload of most events are fairly simple, and look something like this:

{
  "event_type": "subscriber.confirmed",
  "data": {
    "subscriber": "ac79483b-cd28-49c1-982e-8a88e846d7e7"
  }
}

For additional security, you can enable HMAC signing on your webhooks to verify that requests are genuinely coming from Buttondown. When you set a signing key on a webhook, Buttondown will include an X-Buttondown-Signature header with each request.

To enable HMAC signing for a webhook:

1. Go to your webhook settings
2. Add a signing key in the "Signing key" field
3. Save the webhook

The signing key can be any string you choose—make it long and random for best security.

When Buttondown sends a webhook with a signing key enabled, it includes an X-Buttondown-Signature header in the format:

X-Buttondown-Signature: sha256=<signature>

To verify the signature on your end:

import hmac
import hashlib

def verify_signature(payload: bytes, signature_header: str, signing_key: str) -> bool:
    """Verify the HMAC signature from Buttondown webhook."""
    # Extract the signature from the header
    signature = signature_header.replace("sha256=", "")
    
    # Create your own signature
    mac = hmac.new(
        signing_key.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256,
    )
    expected_signature = mac.hexdigest()
    
    # Compare using constant-time comparison to prevent timing attacks
    return hmac.compare_digest(signature, expected_signature)

Node.js:

const crypto = require('crypto');

function verifySignature(payload, signatureHeader, signingKey) {
  const signature = signatureHeader.replace('sha256=', '');
  const expectedSignature = crypto
    .createHmac('sha256', signingKey)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Ruby:

require 'openssl'

def verify_signature(payload, signature_header, signing_key)
  signature = signature_header.gsub('sha256=', '')
  expected_signature = OpenSSL::HMAC.hexdigest('sha256', signing_key, payload)
  
  ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)
end

The signature is computed using HMAC-SHA256 over the raw request body (before JSON parsing), so make sure to verify the signature using the original bytes you received.

You can also use signing keys when sending post requests via automation actions. Simply add a signing_key field to your action's metadata:

{
  "type": "send_post_request",
  "metadata": {
    "url": "https://your-api.com/webhook",
    "signing_key": "your-secret-key-here"
  }
}

We retry up to 3 times if a webhook fails.

1. Log into your Buttondown account
2. Go to Settings
3. Click the Create webhook button:

You'll need to provide the following information:

Enter the URL where Buttondown should send event data. This URL is typically provided by:

• Third-party services (Discord, Slack, etc.)
• Automation platforms (Zapier, Make, n8n)
• Your own application endpoint

Select which events should trigger your webhook. Common event types include:

You can select multiple events for a single webhook.

Once you've configured your webhook, it's recommended to test it:

1. Click the Test webhook button
2. Buttondown will send a test payload to your URL
3. Verify that your receiving service gets the test data

• Types of events