Webhook Verification Information

Security: All webhooks are signed with HMAC-SHA256

Headers:

• X-Webhook-Signature: Contains the signature in format sha256=<hex_signature>
• User-Agent: Always VesuvioPay-Webhooks/1.0
• Content-Type: Always application/json

Verification Process:

1. Get your webhook secret from the webhook configuration
2. Compute HMAC-SHA256 of the raw request body using your secret
3. Compare with the signature from the header (use timing-safe comparison)

Response Requirements:

• Respond with 2xx status code within 30 seconds
• VesuvioPay will retry failed deliveries with exponential backoff
• Use the webhook event id for idempotency (events may be delivered more than once)

Example verification code:

const crypto = require('crypto');

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