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

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

Confirms requests originate from our system
Prevents tampering with webhook payloads
Protects against replay attacks when combined with timestamp validation

Additional Resources

For more implementation examples and best practices, see: https://hookdeck.com/webhooks/guides/how-to-implement-sha256-webhook-signature-verification