​

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 received = Buffer.from(signature, 'hex');
  const expected = Buffer.from(expectedSignature, 'hex');

  // timingSafeEqual throws if the buffers differ in length — check first.
  const isValid =
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);

  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.
• The signature is computed over the exact JSON body Wava sends, using HMAC-SHA256 by default.
• Use the signing key as a plain UTF-8 string. It is 64 hexadecimal characters, but it is not hex-decoded before use — pass it to your HMAC function exactly as shown in your dashboard. Decoding it to 32 raw bytes first produces a valid-looking signature that will never match ours.
• The webhook secret is the signing key (64 characters), not the API secret key (128 characters). Partner accounts receive both in the same response at account creation; only the 64-character signing_key signs webhooks.
• Partner accounts are created with signing enabled and their own signing key, issued once at account creation. For direct API integrations signing is optional — contact soporte@wava.co to enable it.

​

Checking which key signed a delivery

crypto.createHash('sha256').update(yourKey).digest('hex').slice(0, 12)

​

Idempotency