Webhook signature verification

Paymove signs every outgoing webhook request with HMAC-SHA256. This lets you confirm that a notification genuinely came from Paymove, and not from someone who learned your endpoint URL.

Signature verification is mandatory. Without it, anyone who knows your endpoint can send a forged payment notification and have an order fulfilled without paying.

The header

Every request carries a single signature header:

X-Paymove-Signature: t=1708790400,v1=K4oSHnBOYVPuGCRnKv8bDLACmwbHBZPxPC+r24/lqHk=

Component	Description
`t=`	Unix epoch seconds when the message was signed
`v1=`	HMAC-SHA256 signature, base64-encoded. The `v1` prefix allows a future algorithm change without breaking existing integrations

Signing secret

Each webhook has its own secret in the format whsec_<base64>. You receive it in the response to registering the webhook, in the signingSecret field.

Use the entire string including the whsec_ prefix, UTF-8 encoded, as the HMAC key. Do not strip the prefix and do not base64-decode the remainder - this is the single most common cause of failing verification.

If you lose the secret, you can read it again from the GET /api/pay/plugin/webhook/{webhookId} response - there is no need to rotate it for that reason.

Algorithm

Read the X-Paymove-Signature header.
Split the value on the comma into the t=<timestamp> and v1=<signature> parts.
Build the signed content: {timestamp}.{raw_request_body}.
Compute HMAC-SHA256 using the full secret (with prefix) as the key.
Base64-encode the result and prepend v1=.
Compare it with the signature from the header using a timing-safe comparison.

The signature is computed over the raw request body, byte for byte. If your framework parses the JSON and re-serializes it, the result will almost certainly differ. Capture the raw body before parsing - in Express via express.raw({ type: "application/json" }), in Next.js via await request.text().

Code

Node.js

const crypto = require("crypto");

function verifyWebhook(secret, signatureHeader, rawBody) {
  if (!signatureHeader) return false;

  const [tPart, signature] = signatureHeader.split(",", 2);
  if (!tPart?.startsWith("t=") || !signature?.startsWith("v1=")) return false;

  const timestamp = tPart.slice(2);

  // 5-minute tolerance window - protects against replaying an old request
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const hash = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("base64");
  const expected = `v1=${hash}`;

  // timingSafeEqual throws on differing lengths - check the length first
  if (expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Usage in Express:

const express = require("express");
const app = express();

app.post(
  "/api/payments/webhook",
  express.raw({ type: "application/json" }), // raw body, unparsed
  (req, res) => {
    const rawBody = req.body.toString("utf8");

    if (!verifyWebhook(process.env.PAYMOVE_WEBHOOK_SECRET, req.get("X-Paymove-Signature"), rawBody)) {
      return res.status(401).json({ error: "invalid signature" });
    }

    const event = JSON.parse(rawBody);

    // Respond immediately - Paymove applies no timeout,
    // and a slow endpoint blocks processing on the gateway side.
    res.status(200).json({ status: "ok" });

    // Do the fulfilment asynchronously and idempotently
    fulfillOrder(event.orderId ?? event.externalId).catch(console.error);
  }
);

Python

import hmac
import hashlib
import base64
import time


def verify_webhook(secret: str, signature_header: str, raw_body: str) -> bool:
    if not signature_header:
        return False

    parts = signature_header.split(",", 1)
    if len(parts) != 2 or not parts[0].startswith("t=") or not parts[1].startswith("v1="):
        return False

    timestamp, signature = parts[0][2:], parts[1]

    # 5-minute tolerance window
    try:
        if abs(int(time.time()) - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    digest = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).digest()
    expected = "v1=" + base64.b64encode(digest).decode("utf-8")

    return hmac.compare_digest(expected, signature)

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Base64;

public boolean verifyWebhook(String secret, String signatureHeader, String rawBody) throws Exception {
    if (signatureHeader == null) return false;

    String[] parts = signatureHeader.split(",", 2);
    if (parts.length != 2 || !parts[0].startsWith("t=") || !parts[1].startsWith("v1=")) return false;

    String timestamp = parts[0].substring(2);
    String signature = parts[1];

    // 5-minute tolerance window
    long age = Math.abs(Instant.now().getEpochSecond() - Long.parseLong(timestamp));
    if (age > 300) return false;

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] hash = mac.doFinal((timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8));
    String expected = "v1=" + Base64.getEncoder().encodeToString(hash);

    return MessageDigest.isEqual(
        expected.getBytes(StandardCharsets.UTF_8),
        signature.getBytes(StandardCharsets.UTF_8)
    );
}

Test vector

Check your implementation against the values below - skip the tolerance window, since the timestamp is in the past:

Item	Value
Secret	`whsec_dGVzdHNlY3JldHRlc3RzZWNyZXR0ZXN0c2VjcmV0cw==`
Body	`{"event":"payment.completed"}`
Timestamp	`1708790400`
Signed content	`1708790400.{"event":"payment.completed"}`
Expected header	`t=1708790400,v1=1rODbpFCfITTJax9V5WnIWRfrxR0cvvg3yXGVGhlV7s=`

If your function returns a different signature, check in order: that you use the full secret including the whsec_ prefix, that you encode to base64 (not hex), and that you sign the raw body without re-serializing it.

Replay protection

The timestamp is covered by the signature, so it cannot be tampered with - but Paymove itself does not reject old requests. Your server decides how long a signature stays valid. The recommended window is 5 minutes; the examples above already apply it. On top of that, fulfil orders idempotently, keyed on externalId. A redelivered notification must never result in shipping the goods twice.

Rotating the secret

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/rotate-secret \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

The previous secret stops working immediately - there is no period during which both are accepted. Update your own configuration at the same moment, otherwise you will start rejecting genuine notifications.

Introduction

Integrations

Tutorials

Help

Resources

The header

Signing secret

Algorithm

Code

Node.js

Python

Java

Test vector

Replay protection

Rotating the secret

What’s next

Payment statuses

Webhook configuration

​The header

​Signing secret

​Algorithm

​Code

​Node.js

​Python

​Java

​Test vector

​Replay protection

​Rotating the secret

​What’s next

Payment statuses

Webhook configuration

The header

Signing secret

Algorithm

Code

Node.js

Python

Java

Test vector

Replay protection

Rotating the secret

What’s next