Webhook Documentation

Python

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret_key):
    # Extract signature value
    signature_value = signature.split('=')[1]
    
    # Convert payload to JSON string
    payload_str = json.dumps(payload, separators=(',', ':'))
    
    # Compute expected signature
    computed = hmac.new(
        secret_key.encode('utf-8'),
        payload_str.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Compare securely
    return hmac.compare_digest(computed, signature_value)

# Usage
if verify_webhook_signature(payload, signature, "my-secret-key"):
    print("Signature verified!")
else:
    print("Invalid signature!")

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secretKey) {
    // Extract signature value
    const signatureValue = signature.split('=')[1];
    
    // Convert payload to JSON string
    const payloadStr = JSON.stringify(payload);
    
    // Compute expected signature
    const computed = crypto
        .createHmac('sha256', secretKey)
        .update(payloadStr)
        .digest('hex');
    
    // Compare securely
    return crypto.timingSafeEqual(
        Buffer.from(computed, 'hex'),
        Buffer.from(signatureValue, 'hex')
    );
}

// Usage
if (verifyWebhookSignature(payload, signature, "my-secret-key")) {
    console.log("Signature verified!");
} else {
    console.log("Invalid signature!");
}

PHP

<?php
function verifyWebhookSignature($payload, $signature, $secretKey) {
    // Extract signature value
    $signatureValue = explode('=', $signature)[1];
    
    // Convert payload to JSON string
    $payloadStr = json_encode($payload);
    
    // Compute expected signature
    $computed = hash_hmac('sha256', $payloadStr, $secretKey);
    
    // Compare securely
    return hash_equals($computed, $signatureValue);
}

// Usage
if (verifyWebhookSignature($payload, $signature, "my-secret-key")) {
    echo "Signature verified!";
} else {
    echo "Invalid signature!";
}

Webhook URL Requirements

• Must be a valid HTTPS URL
• Should respond with HTTP 200 status code
• Should handle the webhook within 30 seconds
• Should verify the HMAC-SHA256 signature before processing

Security Best Practices

• Always verify the webhook signature before processing
• Store your webhook secret key securely
• Use HTTPS for all webhook endpoints
• Implement idempotency to handle duplicate webhooks
• Log webhook events for debugging and auditing

Error Handling

• Return HTTP 200 for successful webhook processing
• Return HTTP 4xx for invalid requests (malformed payload, invalid signature)
• Return HTTP 5xx for server errors (temporary issues)
• Payment Hub will retry failed webhooks up to 7 times