Webhook Security
Each webhook request includes a signature in the X-PaidCommunities-Signature header. This signature allows you to verify that the requests came from PaidCommunities and weren't tampered with.
Signature Format
The signature header contains a timestamp and a signature value in this format:
X-PaidCommunities-Signature: t=1658461756,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Where:
tis the timestamp when the request was sentv1is the SHA256 HMAC of the timestamp and request body
Verifying Signatures
To verify a webhook's signature:
- Extract the timestamp and signature from the header
- Recreate the signature using your webhook secret
- Compare the signatures to verify the request
const crypto = require('crypto');
function verifyWebhookSignature(payload, sigHeader, secret) {
// Extract timestamp and signature
const [tsString, sigString] = sigHeader.split(',');
const timestamp = parseInt(tsString.split('=')[1]);
const signature = sigString.split('=')[1];
// Optional: Check if the request is too old (e.g., older than 5 minutes)
const fiveMinutes = 5 * 60 * 1000;
if (Date.now() - timestamp > fiveMinutes) {
throw new Error('Request is too old');
}
// Create expected signature
const hmac = crypto.createHmac('sha256', secret);
const payloadToSign = timestamp + '.' + payload;
hmac.update(payloadToSign);
const expectedSignature = hmac.digest('hex');
// Compare signatures
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Example usage
app.post('/webhook', (req, res) => {
const signature = req.headers['x-paidcommunities-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
return res.status(400).send('Invalid signature');
}
// Handle webhook
// ...
// Send a 2xx response code for successful requests
return res.status(200);
});
Preventing Replay Attacks
The timestamp (t) included in the signature header helps prevent replay attacks. By checking the timestamp against the current time, you can reject requests that are too old. The example above includes timestamp validation with a 5-minute tolerance window.
The tolerance window can be adjusted based on your security requirements. A shorter window is more secure but may cause legitimate requests to be rejected if there are network delays.
Finding Your Webhook Secret
Your webhook secret is available in the PaidCommunities dashboard:
- Navigate to Developers > Webhooks
- Find your webhook endpoint
- Click Reveal to view the secret
Never share your webhook secret or commit it to public repositories. If your secret is compromised, generate a new one immediately from the webhook settings page.
Security Best Practices
- Always Verify Signatures: Never process webhooks without verifying their signatures
- Validate Timestamps: Implement timestamp checking to prevent replay attacks
- Store Secrets Securely: Keep your webhook secret secure and never commit it to version control
- Use HTTPS: Only use HTTPS endpoints for receiving webhooks
- Implement Logging: Keep detailed logs of webhook processing for debugging and auditing