Verify HMAC signatures

Verify the integrity of webhook events using HMAC signatures.

To protect your server from unauthorised webhook events, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures for our webhooks. Each webhook event will include a signature calculated using a secret HMAC key and a payload from the webhook. By verifying this signature, you confirm that the webhook was sent by Safepay, and was not modified during transmission.

To verify HMAC signatures, you can either:

• Use one of our libraries.
• Build your own custom solution.

View your shared secret

Safepay signs the webhooks events it sends to your endpoints bny including a signature in the headers sent with each event. The header key is called X-SFPY-SIGNATURE and allows you to verify the integrity of the event. The first step is to locate your shared secret.

• Navigate to your Live Dashboard and then go to Developers > Endpoints.
• Click on View shared secret and then click on the copy-to-clipboard icon.
• Paste the secret key in your code base.

If you generate a new HMAC key, make sure that you can still accept webhooks signed with your previous HMAC key for some time, because:

• It can take some time to propagate the new key in our infrastructure.
• HMAC signatures are calculated when the webhook payload is generated, so any webhook events queued before you saved the new key are signed using your previous key.

Verify using our libraries

You can verify signatures using our:

• PHP library
• JavaScript library

const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
  authType: 'secret',
  host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});

// You can find your endpoint's secret in your 
// webhook settings in the Developer Dashboard
const webhookSecret = '234hjkasd....';
const payload = req.body.raw
const signature = req.headers['X-SFPY-SIGNATURE'];
let event;
try {
  const event = safepay.webhooks.constructEvent(
    payload,
    signature,
    webhookSecret
  );
} catch (err) {
  // On error, log and return the error message
  console.log(`❌ Error message: ${err.message}`);
  res.status(400).send(`Webhook Error: ${err.message}`);
  return;
}

switch (event.type) {
  case 'payment.succeeded':
    const payment = event.data
  case 'payment.failed':
    const error = event.data
  default:
    console.log('Received unknown event type ' + event.type)
}

Verify using your own solution

To build your own solution for verifying HMAC signatures, follow these steps:

const data = Buffer.from(JSON.stringify(payload));

const hash = crypto.createHmac("sha512", secret)
                   .update(data)
                   .digest("hex");