​

Webhook Security

​

Verifying webhooks

1. Verify the signature — API integrations with signing enabled receive an X-Wava-Signature header. See Signature Verification below.
2. Verify the order — After receiving a webhook, call GET /v1/orders/{orderId} with your merchant key to confirm the order status matches what the webhook reported.
3. Use HTTPS — Always use an HTTPS endpoint for your webhook URL in production.

​

Signature verification

​

How it works

​

Request headers

Content-Type: application/json
X-Wava-Event: order_payment
X-Wava-Timestamp: 2024-12-18T10:30:00.000Z
X-Wava-Signature: a1b2c3d4e5f6...
User-Agent: Wava-Webhooks/1.0

​

Verification examples

const crypto = require('crypto');

function verifyWavaWebhook(req, res, next) {
  const signature = req.headers['x-wava-signature'];

  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  const payloadString = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WAVA_WEBHOOK_SECRET)
    .update(payloadString)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
}

import hmac
import hashlib
import json
import os

def verify_webhook_signature(payload, signature):
    secret = os.environ['WAVA_WEBHOOK_SECRET']
    payload_string = json.dumps(payload, separators=(',', ':'))
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

function verifyWebhookSignature($payload, $signature) {
    $secret = $_ENV['WAVA_WEBHOOK_SECRET'];
    $payloadString = json_encode($payload, JSON_UNESCAPED_SLASHES);
    $expected = hash_hmac('sha256', $payloadString, $secret);
    return hash_equals($signature, $expected);
}

​

Important notes

• The X-Wava-Signature is a plain hexadecimal string — no prefix like sha256=.
• Serialize the payload using JSON.stringify() with default options. Property order matters.
• Store your secret in an environment variable — never commit it to source control.
• Signature signing is optional and must be enabled in your integration configuration. Contact support if you need it enabled.

​

Idempotency