Verify Signatures

Overview

Verifying webhook signatures ensures that incoming webhooks are authentic and sent by Coinbase, protecting your application from malicious requests and replay attacks.

Why verify signatures?

Without signature verification, your webhook endpoint is vulnerable to:

Spoofed webhooks: Attackers could send fake event data to your endpoint
Replay attacks: Old webhook events could be resent to trigger duplicate processing
Man-in-the-middle attacks: Modified webhook payloads could go undetected

Always verify webhook signatures in production. Unverified webhooks can lead to security vulnerabilities and data integrity issues.

How it works

When you create a webhook subscription, the response includes a secret that serves as your signing key. Each webhook request includes the signature under the header name: X-Hook0-Signature.

Example signature header

t=1728394718,v0=9f8e7d6c5b4a...,h=content-type x-event-id x-event-type,v1=a1b2c3d4e5f6...

The signature header contains four parts:

Field	Description	Example
`t`	Unix timestamp (seconds) when the webhook was sent	`1728394718`
`v0`	HMAC-SHA256 over `{t}.{body}` — protects the body and timestamp only	`9f8e7d6c5b4a...`
`h`	Space-separated, ordered list of header names included in the `v1` signature	`content-type x-event-id x-event-type`
`v1`	HMAC-SHA256 over `{t}.{h}.{headerValues}.{body}` — also binds the listed headers	`a1b2c3d4e5f6...`

v0 and v1 are both included on every request. v0 includes the timestamp and body; v1 additionally binds the listed headers. Unless you want to bind the headers, which is unnecessary for most use cases, use v0.

Verification process

Extract signature components: Parse the t, h, v0, and v1 values from the header
Build signed payload: Concatenate timestamp.headerNames.headerValues.rawBody
Compute expected signature: Create HMAC-SHA256 hash using your secret
Compare signatures: Use timing-safe comparison to match expected vs. provided
Verify timestamp: Ensure the webhook isn’t too old (prevents replay attacks)

1. Create a verification function

First, handle the verification logic in a reusable function which will:

Parse the signature header to extract the timestamp, header names, and signature
Build the signed payload by concatenating the timestamp, headers, and raw body
Compute the expected signature using HMAC-SHA256
Compare the signatures using a timing-safe comparison to prevent timing attacks
Validate the timestamp to ensure the webhook isn’t too old (replay attack prevention)

verify-webhook.js

const crypto = require('crypto');

/**
 * Verify webhook signature and timestamp
 * @param {string} payload - Raw request body as string
 * @param {string} signatureHeader - X-Hook0-Signature header value
 * @param {string} secret - Webhook secret from the subscription response
 * @param {Object} headers - HTTP headers from webhook request
 * @param {number} maxAgeMinutes - Max age for webhook (default: 5 minutes)
 * @returns {boolean} true if webhook is authentic and within allowed time window
 */
function verifyWebhookSignature(payload, signatureHeader, secret, headers, maxAgeMinutes = 5) {
    try {
        // Parse signature header: t=timestamp,h=headers,v1=signature
        const elements = signatureHeader.split(',');
        const timestamp = elements.find(e => e.startsWith('t=')).split('=')[1];
        const headerNames = elements.find(e => e.startsWith('h=')).split('=')[1];
        const providedSignature = elements.find(e => e.startsWith('v1=')).split('=')[1];

        // Build header values string
        const headerNameList = headerNames.split(' ');
        const headerValues = headerNameList.map(name => headers[name] || '').join('.');

        // Build signed payload
        const signedPayload = `${timestamp}.${headerNames}.${headerValues}.${payload}`;

        // Compute expected signature
        const expectedSignature = crypto
            .createHmac('sha256', secret)
            .update(signedPayload, 'utf8')
            .digest('hex');

        // Compare signatures securely
        const signaturesMatch = crypto.timingSafeEqual(
            Buffer.from(expectedSignature, 'hex'),
            Buffer.from(providedSignature, 'hex')
        );

        // Verify timestamp to prevent replay attacks
        const webhookTime = parseInt(timestamp) * 1000; // Convert to milliseconds
        const currentTime = Date.now();
        const ageMinutes = (currentTime - webhookTime) / (1000 * 60);

        if (ageMinutes > maxAgeMinutes) {
            console.error(`Webhook timestamp exceeds maximum age: ${ageMinutes.toFixed(1)} minutes > ${maxAgeMinutes} minutes`);
            return false;
        }

        return signaturesMatch;

    } catch (error) {
        console.error('Webhook verification error:', error);
        return false;
    }
}

2. Verify webhooks in your application

Now integrate the verification function into your webhook endpoint. This example shows:

How to configure Express to preserve the raw request body (required for signature verification)
How to extract the signature header and webhook secret
How to call the verification function before processing the webhook
How to handle both valid and invalid webhooks appropriately

Important: You must use express.raw() middleware instead of express.json() to preserve the raw request body. The signature is computed against the raw bytes, so parsing the JSON first will break verification.

webhook-endpoint.js

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

// Important: Get raw body for signature verification
app.use(express.raw({ type: "application/json" }));

app.post("/webhook", (req, res) => {
    // Step 1: Extract the raw payload (must be string for signature verification)
    const payload = req.body.toString();

    // Step 2: Get the signature from the X-Hook0-Signature header
    const signature = req.headers["x-hook0-signature"];

    // Step 3: Get your webhook secret (from the subscription response)
    const secret = process.env.WEBHOOK_SECRET;

    // Step 4: Verify the webhook signature
    if (verifyWebhookSignature(payload, signature, secret, req.headers)) {
        console.log("✅ Authentic webhook");

        // Step 5: Parse the JSON payload (only after verification!)
        const event = JSON.parse(payload);

        // Step 6: Process your webhook event
        console.log("Transaction detected:", event.data.transactionHash);
        // Add your business logic here...

        // Step 7: Return 200 to acknowledge receipt
        res.status(200).send("OK");
    } else {
        console.log("❌ Invalid webhook - rejected");
        res.status(400).send("Invalid signature");
    }
});

Example webhook payload

Here’s what a complete webhook request looks like:

webhook-payload.json

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "onchain.activity.detected",
  "createdAt": "2025-10-08T13:58:38.681893Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "networkId": "base-mainnet",
    "blockNumber": 12345678,
    "blockHash": "0xabc123...",
    "transactionHash": "0xdef456...",
    "logIndex": 42,
    "contractAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "eventName": "Transfer",
    "from": "0xf20d2e37514195ebedb0bc735ba6090ce103d38c",
    "to": "0x1234567890123456789012345678901234567890",
    "value": "1000000"
  }
}

The webhook request will include these HTTP headers:

HTTP headers

POST /webhook HTTP/1.1
Host: your-webhook-url.com
Content-Type: application/json
X-Event-Id: 3a3dd092-55ce-4832-97d9-0e1ab928c79b
X-Event-Type: onchain.activity.detected
X-Hook0-Signature: t=1728394718,v0=9f8e7d6c5b4a...,h=content-type x-event-id x-event-type,v1=a1b2c3d4e5f6...
Content-Length: 512

Security best practices

Store secrets securely

Never hardcode webhook secrets in your code. Use environment variables or a secure secrets manager:

// ✅ Good - using environment variables
const secret = process.env.WEBHOOK_SECRET;

// ❌ Bad - hardcoded secret
const secret = "whsec_abc123...";

Use HTTPS only

Always use HTTPS endpoints for your webhooks. HTTP endpoints expose your webhook data to interception and tampering.

Implement rate limiting

Add rate limiting to your webhook endpoint to prevent abuse:

const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100 // limit each IP to 100 requests per minute
});

app.post('/webhook', webhookLimiter, (req, res) => {
  // Your webhook handler
});

Validate timestamp window

The default 5-minute window prevents replay attacks. Adjust based on your needs, but don’t make it too large:

// Default 5 minutes is recommended
verifyWebhookSignature(payload, signature, secret, headers, 5);

// For high-security applications, use a shorter window
verifyWebhookSignature(payload, signature, secret, headers, 1);

Log verification failures

Track failed verification attempts to detect potential security issues:

if (!verifyWebhookSignature(payload, signature, secret, headers)) {
  console.error('Webhook verification failed', {
    timestamp: new Date().toISOString(),
    ip: req.ip,
    signature: signature,
    // Don't log the payload as it may contain sensitive data
  });
  res.status(400).send("Invalid signature");
  return;
}

Error handling

Handle common verification failures gracefully:

error-handling.js

app.post('/webhook', (req, res) => {
  const payload = req.body.toString();
  const signature = req.headers['x-hook0-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  // Check for missing signature
  if (!signature) {
    console.error('Missing X-Hook0-Signature header');
    return res.status(400).send('Missing signature');
  }

  // Check for missing secret
  if (!secret) {
    console.error('Webhook secret not configured');
    return res.status(500).send('Server configuration error');
  }

  try {
    const isValid = verifyWebhookSignature(payload, signature, secret, req.headers);

    if (!isValid) {
      console.error('Invalid webhook signature');
      return res.status(400).send('Invalid signature');
    }

    // Process the webhook
    const event = JSON.parse(payload);

    // Handle specific event types
    if (event.type === 'onchain.activity.detected') {
      // Process transaction event
      console.log('Transaction detected:', event.data.transactionHash);
    }

    res.status(200).send('OK');

  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).send('Processing error');
  }
});

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Overview

Why verify signatures?

How it works

1. Create a verification function

2. Verify webhooks in your application

Example webhook payload

Security best practices

Error handling

What to read next

​Overview

​Why verify signatures?

​How it works

​1. Create a verification function

​2. Verify webhooks in your application

​Example webhook payload

​Security best practices

​Error handling

​What to read next

Overview

Why verify signatures?

How it works

1. Create a verification function

2. Verify webhooks in your application

Example webhook payload

Security best practices

Error handling

What to read next