Webhook Security

All webhook requests include a signature header for verification. You should always verify this signature to ensure the request is authentic.

X-Reload-Signature: t=1679743200,v1=5257a869b7c07c88...

The signature is composed of a timestamp and a hash value separated by a comma. The hash is generated using HMAC-SHA256 with your webhook secret.

Signature Verification

To verify the signature:

1. Extract the timestamp and signature from the header
2. Recreate the signature using your webhook secret\
3. Compare the signatures using a constant-time comparison function

// Node.js example
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  // Extract timestamp and signature value
  const [timestampPart, signaturePart] = signature.split(',');
  const timestamp = timestampPart.replace('t=', '');
  const providedSignature = signaturePart.replace('v1=', '');

  // Recreate the signature
  const expectedPayload = timestamp + "." + JSON.stringify(payload);
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(expectedPayload)
    .digest("hex");

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(providedSignature),
    Buffer.from(expectedSignature)
  );
}

Best Practices

• Verify signatures: Always verify the webhook signature to ensure the request is authentic.
• Respond quickly: Your webhook endpoint should respond with a 2xx status code as quickly as possible, ideally within 5 seconds.
• Process asynchronously: If your webhook handler needs to perform time-consuming operations, acknowledge the webhook first and then process it asynchronously.
• Implement idempotency: Webhooks may be delivered more than once in rare cases. Design your webhook handler to be idempotent.
• Monitor failures: Keep track of webhook delivery failures and implement a retry mechanism if needed.
• Use HTTPS endpoints: Always use HTTPS for your webhook endpoints to ensure secure data transmission.
• Implement proper error handling: Your webhook handler should gracefully handle unexpected payloads or errors.

📘

Webhook Testing

You can test your webhook implementation by using the sandbox environment. All events triggered in the sandbox environment will be sent to your configured webhook endpoints, allowing you to verify your implementation without affecting production data.