Webhook Authentication with SHA256

Overview

Our webhooks use HMAC-SHA256 signature verification to ensure request authenticity and security.

How It Works

Signing Secret: Each webhook endpoint receives a unique signing secret
Signature Generation: We create an HMAC-SHA256 hash of the request payload using your signing secret
Header Delivery: The signature is sent with each webhook request in the x-signature header

Implementation Steps

Retrieve your signing secret from the provided secure link
Extract the signature from the x-signature header in incoming requests
Generate your own signature by creating an HMAC-SHA256 hash of the request data using your signing secret
Compare signatures to verify the request authenticity

Example Implementation

TypeScript

import crypto from 'crypto';

interface WebhookRequest {
  headers: { [key: string]: string };
  data: string;
}

function verifyWebhookSignature(
  request: WebhookRequest,
  signingSecret: string,
): boolean {
  // Extract signature from header
  const receivedSignature = request.headers['x-signature'];

  if (!receivedSignature) {
    throw new Error('Missing x-signature header');
  }

  // Generate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(request.data)
    .digest('hex');

  // Compare signatures securely
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature),
    Buffer.from(expectedSignature),
  );
}

// Usage example
function handleWebhook(request: WebhookRequest, signingSecret: string) {
  try {
    if (verifyWebhookSignature(request, signingSecret)) {
      // Process webhook payload
      const payload = JSON.parse(request.data);
      console.log('Webhook verified and processed:', payload);
    } else {
      console.error('Webhook signature verification failed');
      // Reject the request
    }
  } catch (error) {
    console.error('Webhook processing error:', error);
  }
}

Security Benefits

Authenticity: Confirms requests originate from our system
Integrity: Prevents tampering with webhook payloads
Replay Protection: Protects against replay attacks when combined with timestamp validation

Additional Resources

For more implementation examples and best practices, see: How to Implement SHA256 Webhook Signature Verification