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.

The signing key

The signature is generated using your secret API key (sk_test_ for test webhooks, sk_live_ for live webhooks) — the same key you use to authenticate API requests. There is no separate webhook secret.

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 JSON.stringify(payload.data) — that is, only the inner data object of the webhook payload, serialized as JSON — using your secret key. The signature does not cover the outer {event, data} envelope, only the data object inside it.

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;

  // Sign ONLY the inner `data` object of the webhook payload, not the full body.
  const expectedSignature = crypto
    .createHmac('sha512', secretKey)
    .update(JSON.stringify(req.body.data))
    .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']

    # Sign ONLY the inner `data` object of the webhook payload, not the full body.
    data = request.json.get('data')
    expected = hmac.new(
        secret_key.encode('utf-8'),
        json.dumps(data).encode('utf-8'),
        hashlib.sha512
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

PHP

// Note: the signed content is the inner `data` object of the webhook payload,
// serialized as JSON — not the full request body.
function verifyWebhookSignature($dataJson, $signatureHeader) {
    $secretKey = getenv('IVORYPAY_SECRET_KEY');
    $expectedSignature = hash_hmac('sha512', $dataJson, $secretKey);

    return hash_equals($expectedSignature, $signatureHeader);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_IVORYPAY_SIGNATURE'] ?? '';
$decoded = json_decode($payload, true);
$dataJson = json_encode($decoded['data']);

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

// Process the verified webhook
$event = $decoded['event'];
http_response_code(200);

Go

package main

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

// Sign ONLY the inner `data` object (re-serialized as JSON), not the full body.
func verifySignature(dataJSON []byte, signature string) bool {
    mac := hmac.New(sha512.New, []byte(os.Getenv("IVORYPAY_SECRET_KEY")))
    mac.Write(dataJSON)
    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")

    var payload struct {
        Event string          `json:"event"`
        Data  json.RawMessage `json:"data"`
    }
    if err := json.Unmarshal(body, &payload); err != nil {
        http.Error(w, "Invalid payload", http.StatusBadRequest)
        return
    }

    if !verifySignature([]byte(payload.Data), 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 for the relevant environment (not the API key). The signed content is JSON.stringify(payload.data) — only the inner data object of the webhook payload, NOT the full {event, data} request body. The signature is in the x-ivorypay-signature header as a hex string.