---
updatedAt: 2026-07-20T19:29:03.000Z
agentTools:
  projectIndex: https://developers.pandadoc.com/llms.txt
---

# How to Verify Webhook Authenticity

Implement HMAC-SHA256 signature verification to ensure webhook requests are authentic and haven't been tampered with.

## Problem

You need to verify that incoming webhook requests are actually from PandaDoc and haven't been tampered with, preventing spoofed requests from malicious actors.

## Prerequisites

* Active webhook subscription
* Access to your shared key from the Developer Dashboard(Dev Center)
* Basic understanding of HMAC-SHA256 cryptographic signatures

## Solution

### Step 1: Retrieve Your Shared Key

1. Navigate to the [Developer Dashboard](https://app.pandadoc.com/a/#/api-dashboard/configuration)
2. Locate your webhook subscription
3. Copy the shared key (treat this like a password)

> 🚧 Protect Your Shared Key
>
> Treat your shared key like a password to prevent others from generating a webhook with a payload that could pass a signature verification test.

### Step 2: Understand How PandaDoc Delivers the Signature

Each webhook request arrives as a POST to your registered endpoint with a signature query parameter appended automatically:

```http
POST https://yourdomain.com/webhook-handler/?signature=a1b2c3...
```

No additional configuration is required in the Developer Dashboard, the signature is always sent.

### Step 3: Implement Signature Verification

Choose your preferred programming language:

```python Python Verification
import hmac
import hashlib

def verify_webhook_signature(shared_key, request_body, received_signature):
    # Generate expected signature
    expected_signature = hmac.new(
        str(shared_key).encode('utf-8'),
        str(request_body).encode('utf-8'),
        digestmod=hashlib.sha256
    ).hexdigest()

    # Use timing-safe comparison
    return hmac.compare_digest(expected_signature, received_signature)
```

```php PHP Verification
<?php
function verifyWebhookSignature($sharedKey, $requestBody, $receivedSignature) {
    // Generate expected signature
    $expectedSignature = hash_hmac('sha256', $requestBody, $sharedKey);

    // Use timing-safe comparison
    return hash_equals($expectedSignature, $receivedSignature);
}
?>
```

```csharp C# Verification
using System;
using System.Security.Cryptography;
using System.Text;

public static bool VerifyHMACSHA256(string sharedKey, string requestBody, string receivedSignature) {
    byte[] key = Encoding.UTF8.GetBytes(sharedKey);
    using (HMACSHA256 hmac256 = new HMACSHA256(key))
    {
        var hashedSource = hmac256.ComputeHash(Encoding.UTF8.GetBytes(requestBody));

        if (hashedSource == null || hashedSource.Length == 0)
        {
            return false;
        }

        var expectedSignature = new StringBuilder();
        for (int i = 0; i < hashedSource.Length; i++)
        {
            expectedSignature.AppendFormat("{0:x2}", hashedSource[i]);
        }

        // Use timing-safe comparison
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expectedSignature.ToString()),
            Encoding.UTF8.GetBytes(receivedSignature)
        );
    }
}
```

```javascript Node.js Verification
const crypto = require("crypto");

function verifyWebhookSignature(sharedKey, requestBody, receivedSignature) {
  // Generate expected signature
  const hmac = crypto.createHmac("sha256", sharedKey);
  hmac.update(requestBody);
  const expectedSignature = hmac.digest("hex");

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, "hex"),
    Buffer.from(receivedSignature, "hex")
  );
}
```

### Step 4: Handle Verification Failures

When signature verification fails:

1. **Log the event** for security monitoring
2. **Return HTTP 403** (Forbidden) status
3. **Do not process** the webhook payload
4. **Alert your security team** if multiple failures occur

### Step 5: Test Your Implementation

1. Create a test webhook subscription
2. Trigger a document event
3. Verify your endpoint correctly validates the signature
4. Test with an invalid signature to confirm rejection

## Verification

To confirm your implementation works:

1. **Valid signature test**: Process a real webhook and verify it passes
2. **Invalid signature test**: Modify the received signature and confirm it's rejected
3. **Timing attack protection**: Use timing-safe comparison functions
4. **Error handling**: Confirm proper HTTP status codes are returned

## Troubleshooting

### Common Issues

**Signature verification always fails:**

* Ensure you're using the raw HTTP body (not parsed JSON)
* Check that your shared key is correct
* Verify the signature is extracted from the correct URL parameter

**Security warnings:**

* Use `hmac.compare_digest()` in Python or `crypto.timingSafeEqual()` in Node.js
* Avoid string comparison operators that are vulnerable to timing attacks

**Performance concerns:**

* Signature verification is fast (microseconds)
* Cache the shared key rather than fetching it for each request
* Consider implementing rate limiting

## Security Best Practices

1. **Store shared keys securely** - Use environment variables or secure vaults
2. **Use timing-safe comparison** - Prevent timing attack vulnerabilities
3. **Implement logging** - Track verification failures for security monitoring
4. **Regular key rotation** - Update shared keys periodically
5. **IP allowlisting** - Combine with signature verification for defense in depth

## Related

* [How to Set Up Webhook Notifications](../docs/webhook-setup) - Initial webhook configuration
* [How to Deduplicate Webhook Deliveries](../docs/webhook-deduplication) - Process retries safely with event IDs
* [How to Debug and Monitor Webhooks](../docs/webhook-debugging) - Troubleshooting and monitoring
* [Webhook Events Reference](../docs/webhook-events) - Event specifications and IP allowlist
* [Understanding Webhooks](../docs/webhooks-concepts) - Security architecture concepts