Webhook Payload Generator

Why Use a Webhook Payload Generator?

Testing webhook integrations can be challenging because you need to trigger real events in third-party systems, which often requires complex setup or can have side effects. A webhook payload generator allows you to:

• Test Without Real Events: Generate realistic webhook payloads without triggering actual events in production systems
• Verify Signature Authentication: Generate and verify HMAC signatures to ensure your webhook endpoint correctly validates incoming requests
• Debug Integration Issues: Test different payload structures and edge cases without affecting live data
• Learn Provider Formats: Explore the structure of webhooks from different providers like Stripe, GitHub, Slack, and more
• Development & Staging: Test webhook handling in development and staging environments before going live

Understanding HMAC Signatures

HMAC (Hash-based Message Authentication Code) signatures are the standard way to secure webhooks. Here's how they work:

The Signature Process

1. Shared Secret: Both the webhook sender and receiver know a shared secret key
2. Hash Generation: The sender creates a hash of the payload using the secret and a cryptographic algorithm (SHA256, SHA1, etc.)
3. Header Transmission: The signature is sent in a specific HTTP header along with the payload
4. Verification: The receiver regenerates the hash using the same secret and compares it to the received signature

Common Signature Formats

Different providers use different signature formats:

• Stripe: t=timestamp,v1=signature - Includes timestamp for replay protection
• GitHub: sha256=signature - Simple SHA256 hash with prefix
• Slack: v0=signature with v0:timestamp:body signing format
• Shopify: Base64-encoded HMAC-SHA256
• Twilio: SHA1 signature with URL and parameters

Webhook Security Best Practices

1. Always Verify Signatures

Never trust webhook data without signature verification. An attacker could send fake webhook requests to your endpoint if you don't verify signatures.

// Example: Verifying a webhook signature (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

2. Use HTTPS Endpoints

Always use HTTPS for webhook endpoints to protect data in transit. Webhooks may contain sensitive information like customer data, payment details, or authentication tokens.

3. Implement Replay Protection

Use timestamps or nonces to prevent replay attacks where an attacker resends a valid webhook request:

• Check that the timestamp is recent (within 5 minutes for most use cases)
• Store and check nonce values to ensure they're only used once
• Reject requests with old timestamps

4. Store Secrets Securely

• Never commit webhook secrets to version control
• Use environment variables or secret management services
• Rotate secrets periodically
• Use different secrets for development, staging, and production

5. Handle Errors Gracefully

• Return 2xx status codes for successfully processed webhooks
• Return 4xx for client errors (invalid signature, malformed payload)
• Return 5xx for server errors that should be retried
• Log all webhook attempts for debugging and auditing

Testing Your Webhook Integration

Step 1: Set Up Your Development Environment

Create a local webhook endpoint or use a service like ngrok to expose your local server:

# Using ngrok to create a public URL
ngrok http 3000
# Your webhook URL: https://abc123.ngrok.io/webhook

Step 2: Generate a Test Payload

1. Select your provider (Stripe, GitHub, etc.)
2. Choose the event type you want to test
3. Edit the payload if needed
4. Enter your webhook secret
5. Generate the HMAC signature

Step 3: Send the Test Payload

Use the "Send Test Payload" feature to post the generated payload to your endpoint, or copy the curl command:

curl -X POST https://your-endpoint.com/webhook \\
  -H "Content-Type: application/json" \\
  -H "X-Webhook-Signature: sha256=abc123..." \\
  -d '{"event": "test"}'

Step 4: Verify Signature

Test that your webhook endpoint correctly verifies signatures using the "Verify Signature" section. This helps you debug signature validation logic.

Common Provider Implementations

Stripe Webhooks

Stripe uses Stripe-Signature header with format: t=timestamp,v1=signature

// Stripe signature verification
const stripe = require('stripe');
const sig = request.headers['stripe-signature'];
try {
  const event = stripe.webhooks.constructEvent(
    request.body,
    sig,
    endpointSecret
  );
  // Handle the event
} catch (err) {
  // Invalid signature
}

GitHub Webhooks

GitHub uses X-Hub-Signature-256 header with format: sha256=signature

// GitHub signature verification
const crypto = require('crypto');
const signature = request.headers['x-hub-signature-256'];
const hmac = crypto.createHmac('sha256', secret);
const digest = 'sha256=' + hmac.update(request.body).digest('hex');
const isValid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(digest)
);

Slack Webhooks

Slack uses X-Slack-Signature with timestamp-based signing:

// Slack signature verification
const timestamp = request.headers['x-slack-request-timestamp'];
const signature = request.headers['x-slack-signature'];

// Check timestamp is recent (within 5 minutes)
if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
  throw new Error('Old timestamp');
}

const sigBasestring = `v0:${timestamp}:${request.body}`;
const mySignature = 'v0=' +
  crypto.createHmac('sha256', secret)
    .update(sigBasestring)
    .digest('hex');

Troubleshooting Common Issues

Signature Verification Fails

Problem: Generated signature doesn't match what your endpoint expects

Solutions:

• Ensure you're using the correct algorithm (SHA256 vs SHA1)
• Check that you're signing the exact payload bytes (no JSON formatting changes)
• Verify the secret matches exactly
• For Stripe/Slack, ensure timestamp is included in the signed data
• Check for character encoding issues (UTF-8)

Invalid JSON

Problem: Webhook payload fails to parse as JSON

Solutions:

• Validate JSON using the Monaco editor's built-in validation
• Check for trailing commas (not valid in strict JSON)
• Ensure proper string escaping
• Verify Content-Type header is application/json

Timeout Issues

Problem: Webhook requests timeout

Solutions:

• Webhook endpoints should respond quickly (< 5 seconds)
• Process webhooks asynchronously in a queue
• Return 2xx immediately, then process
• Implement retry logic with exponential backoff

Missing Headers

Problem: Required headers not being sent

Solutions:

• Use the Custom Headers feature to add additional headers
• Check provider documentation for required headers
• Some providers require API version headers
• Include User-Agent if provider requires it

Provider Documentation Links

• Stripe: Webhooks Documentation
• GitHub: Webhooks Guide
• Slack: Verifying Requests
• Shopify: Webhooks Configuration
• Twilio: Webhook Security
• SendGrid: Event Webhook
• Discord: Interactions