Signature Verification

Every webhook request from Paxos Labs includes a cryptographic signature that lets you confirm the request is authentic and hasn’t been tampered with. Always verify signatures before processing webhook payloads.

Headers

Each webhook POST request includes these headers:

Header	Example	Description
`X-PAXOS-LABS-TIMESTAMP`	`2026-04-07T18:06:40.000Z`	RFC 3339 UTC timestamp of event creation. Concatenated with the payload before signing.
`X-PAXOS-LABS-SIGNATURE`	`a3f2...9b01`	HMAC-SHA256 hex digest of the timestamp and payload
`Content-Type`	`application/json`	Always JSON
`User-Agent`	`PaxosLabs-Webhooks/1.0`	Identifies the sender

Signature Scheme

X-PAXOS-LABS-SIGNATURE contains the raw hex-encoded HMAC-SHA256 digest. The timestamp used in the HMAC computation is sent in the separate X-PAXOS-LABS-TIMESTAMP header.

Verification Algorithm

Read the timestamp and signature headers

Read X-PAXOS-LABS-TIMESTAMP for the RFC 3339 timestamp and X-PAXOS-LABS-SIGNATURE for the hex signature.

Check the timestamp

Reject requests where the timestamp is more than 5 minutes from your server’s current time. This protects against replay attacks.

Construct the signed payload

Concatenate the timestamp, a literal period (.), and the raw request body (the exact bytes received — do not parse and re-serialize):

{timestamp}.{raw_body}

Compute the expected signature

Calculate an HMAC-SHA256 using your endpoint’s signing secret as the key and the constructed string as the message. Hex-encode the result.

Compare signatures

Use a constant-time comparison to check that your computed signature matches the v1 value from the signature header. This prevents timing attacks.

Implementation Examples

Node.js
Python
Go

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

function verifyWebhookSignature(rawBody, signatureHeader, timestampHeader, secret) {
  const timestamp = new Date(timestampHeader)
  if (Number.isNaN(timestamp.getTime())) {
    throw new Error('Invalid timestamp header')
  }

  if (Math.abs(Date.now() - timestamp.getTime()) / 1000 > TOLERANCE_SECONDS) {
    throw new Error('Timestamp outside tolerance — possible replay attack')
  }

  const signedPayload = `${timestampHeader}.${rawBody}`
  const expected = createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  const received = Buffer.from(signatureHeader, 'hex')
  const expectedBuf = Buffer.from(expected, 'hex')

  if (received.length !== expectedBuf.length ||
      !timingSafeEqual(received, expectedBuf)) {
    throw new Error('Invalid signature')
  }
}

Use timingSafeEqual instead of === to prevent timing side-channel attacks.

import hashlib, hmac
from datetime import datetime, timezone

TOLERANCE_SECONDS = 300

def verify_webhook_signature(raw_body, signature_header, timestamp_header, secret):
    ts = datetime.fromisoformat(timestamp_header)
    now = datetime.now(timezone.utc)

    if abs((now - ts).total_seconds()) > TOLERANCE_SECONDS:
        raise ValueError("Timestamp outside tolerance — possible replay attack")

    signed_payload = f"{timestamp_header}.{raw_body}".encode()
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature_header, expected):
        raise ValueError("Invalid signature")

hmac.compare_digest provides constant-time comparison in Python.

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"math"
	"time"
)

const ToleranceSeconds = 300

func VerifySignature(body []byte, sigHeader, tsHeader, secret string) error {
	ts, err := time.Parse(time.RFC3339, tsHeader)
	if err != nil {
		return fmt.Errorf("invalid timestamp header: %w", err)
	}

	if math.Abs(time.Since(ts).Seconds()) > ToleranceSeconds {
		return fmt.Errorf("timestamp outside tolerance")
	}

	mac := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(mac, "%s.%s", tsHeader, body)
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(sigHeader), []byte(expected)) {
		return fmt.Errorf("invalid signature")
	}

	return nil
}

hmac.Equal provides constant-time comparison in Go’s standard library.

Best Practices

Always verify before processing

Never process a webhook payload without verifying the signature first. An unverified payload could be forged by a malicious actor.

Use constant-time comparison

Standard string comparison (===, ==) leaks timing information that attackers can exploit. Always use timingSafeEqual (Node.js), hmac.compare_digest (Python), or hmac.Equal (Go).

Enforce a replay window

Reject events where the timestamp is more than 5 minutes from your server’s clock. This prevents captured requests from being replayed later.

Use the raw request body

Compute the HMAC over the exact bytes received in the HTTP body. Parsing to JSON and re-serializing can change whitespace or key ordering, producing a different signature.

Store secrets securely

Keep your signing secret in a secrets manager or encrypted environment variable — never hard-code it or commit it to source control.

Respond quickly

Return a 2xx status code within 10 seconds. Move heavy processing to a background queue so the webhook handler returns immediately.

Handle duplicates idempotently

Use the event id field to deduplicate. Store processed event IDs and skip any that you’ve already handled.

Troubleshooting

Symptom	Cause	Fix
Signature mismatch	Re-serialized body instead of raw bytes	Use the raw HTTP body for HMAC computation
Timestamp rejection	Server clock drift	Sync your server with NTP; widen tolerance if needed
`401` on test events	Wrong secret	Verify you’re using the correct `pxlwh_` secret for this endpoint
Secret lost	Secret was not saved at creation	Delete the endpoint and create a new one

Documentation Index

​Headers

​Signature Scheme

​Verification Algorithm

​Implementation Examples

​Best Practices

​Troubleshooting

Headers

Signature Scheme

Verification Algorithm

Implementation Examples

Best Practices

Troubleshooting