Webhook Security

How to verify webhook signatures to ensure authenticity.

Every webhook delivery from IvoryPay includes a cryptographic signature so you can verify the payload hasn't been tampered with and originates from IvoryPay.

Signature header

IvoryPay signs every webhook payload using HMAC-SHA512 and includes the signature in the x-ivorypay-signature header.

Your secret key

The signature is generated using your Secret Key, which you can find in the IvoryPay Dashboard under Settings → API Keys. This is separate from your API key.

Never expose your secret key. It should only be stored as an environment variable on your server. If compromised, regenerate it immediately from the dashboard.

How to verify

Step 1: Extract the signature

Read the x-ivorypay-signature header from the incoming request.

Step 2: Compute the expected signature

Generate an HMAC-SHA512 hash of the raw JSON request body using your secret key.

Step 3: Compare

Compare your computed hash with the signature header. If they match, the webhook is authentic.

Implementation examples

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(req) {
  const signature = req.headers['x-ivorypay-signature'];
  const secretKey = process.env.IVORYPAY_SECRET_KEY;

  const expectedSignature = crypto
    .createHmac('sha512', secretKey)
    .update(JSON.stringify(req.body))
    .digest('hex');

  return signature === expectedSignature;
}

// Usage in Express
app.post('/webhooks/ivorypay', express.json(), (req, res) => {
  if (!verifyWebhookSignature(req)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the verified webhook
  res.status(200).send('OK');
});

Python

import hmac
import hashlib
import json
import os

def verify_webhook_signature(request):
    signature = request.headers.get('x-ivorypay-signature')
    secret_key = os.environ['IVORYPAY_SECRET_KEY']

    expected = hmac.new(
        secret_key.encode('utf-8'),
        json.dumps(request.json).encode('utf-8'),
        hashlib.sha512
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

PHP

function verifyWebhookSignature($payload, $signatureHeader) {
    $secretKey = getenv('IVORYPAY_SECRET_KEY');
    $expectedSignature = hash_hmac('sha512', $payload, $secretKey);

    return hash_equals($expectedSignature, $signatureHeader);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_IVORYPAY_SIGNATURE'] ?? '';

if (!verifyWebhookSignature($payload, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Process the verified webhook
$event = json_decode($payload, true);
http_response_code(200);

Go

package main

import (
    "crypto/hmac"
    "crypto/sha512"
    "encoding/hex"
    "io"
    "net/http"
    "os"
)

func verifySignature(body []byte, signature string) bool {
    mac := hmac.New(sha512.New, []byte(os.Getenv("IVORYPAY_SECRET_KEY")))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("x-ivorypay-signature")

    if !verifySignature(body, signature) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    w.WriteHeader(http.StatusOK)
    // Process the verified webhook
}

Security best practices

1. Always verify signatures — Never process a webhook without verification

2. Use timing-safe comparison — Use crypto.timingSafeEqual (Node.js), hmac.compare_digest (Python), or hash_equals (PHP) to prevent timing attacks

3. Verify via API — After signature verification, call the Verify Transaction endpoint for an additional layer of confirmation before irreversible actions

4. Use HTTPS — Your webhook URL should always use HTTPS

5. Restrict IP addresses — If possible, whitelist IvoryPay's IP addresses for your webhook endpoint

6. Reject replays — Consider checking timestamps to reject old webhook deliveries

---

For AI assistants: Signature verification uses HMAC-SHA512. The key is the merchant's secret key (not API key). The signed content is JSON.stringify(requestBody). The signature is in the x-ivorypay-signature header as a hex string.