🔒Validating Webhook Signatures

How to verify that a webhook was genuinely sent by PlannrCRM

Every webhook request sent by Plannr includes an X-Signature header. This is an HMAC-SHA256 signature of the raw request body, computed using your webhook subscription's signing_secret. By verifying this signature before processing a webhook, you can be confident the payload was sent by Plannr and has not been tampered with in transit.

Step 1 — Retrieve your signing secret

A unique 60-character signing_secret is automatically generated when a webhook subscription is created. It is returned in the response body whenever you create, update, or retrieve a webhook subscription through the API.

The signing secret is not currently displayed in the Plannr UI. Retrieve it via the API and store it securely in your application.

Make a GET request to retrieve all of your webhook subscriptions and their secrets:

GET /api/v2/webhook-subscriptions

Example response:

{
  "data": [
    {
      "uuid": "53f22fe4-3731-4cdc-aa12-e65bd0b15e52",
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "signing_secret": "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhIjKlMnOpQrSt",
      "url": "https://api.example.com/webhooks",
      "events": ["account.created", "client.updated"],
      "last_outgoing_webhook_call_at": "2024-03-01T14:22:11+00:00"
    }
  ]
}

Treat your signing_secret like a password. Never expose it in client-side code, logs, or version control. Store it securely using environment variables or a secrets manager.

Step 2 — Understand the signature

When Plannr sends a webhook to your endpoint, the request will include:

X-Signature — an HMAC-SHA256 hex digest of the raw request body, keyed with your signing_secret
Content-Type: application/json — the body is a JSON payload

Example headers received on your endpoint:

POST /webhooks HTTP/1.1
Content-Type: application/json
X-Signature: 3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4

Step 3 — Verify the signature

To validate the webhook, compute your own HMAC-SHA256 signature of the raw request body using your signing_secret, then compare it against the X-Signature header. If they match, the webhook is genuine.

Always use the raw, unparsed request body when computing the signature — not a re-serialised version of the parsed JSON. Parsing and re-serialising can alter whitespace or key ordering, causing the signature check to fail.

import hmac
import hashlib

raw_body = request.body
x_signature = request.headers.get("X-Signature", "")
signing_secret = "your-signing-secret-here"

expected = hmac.new(
    key=signing_secret.encode("utf-8"),
    msg=raw_body,
    digestmod=hashlib.sha256,
).hexdigest()

if expected != x_signature:
    raise Exception("Invalid signature")

payload = json.loads(raw_body)

const crypto = require("crypto");

const rawBody = req.body; // use express.raw() middleware
const xSignature = req.headers["x-signature"];
const signingSecret = "your-signing-secret-here";

const expected = crypto
  .createHmac("sha256", signingSecret)
  .update(rawBody)
  .digest("hex");

if (expected !== xSignature) {
  throw new Error("Invalid signature");
}

const payload = JSON.parse(rawBody.toString("utf8"));

using System.Security.Cryptography;
using System.Text;

var rawBody = await new StreamReader(request.Body).ReadToEndAsync();
var xSignature = request.Headers["X-Signature"].FirstOrDefault() ?? string.Empty;
var signingSecret = "your-signing-secret-here";

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingSecret));
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
var expected = Convert.ToHexString(hash).ToLowerInvariant();

if (expected != xSignature.ToLowerInvariant())
    return Results.Unauthorized();

var payload = JsonSerializer.Deserialize<JsonElement>(rawBody);

$rawBody       = file_get_contents('php://input');
$xSignature    = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$signingSecret = 'your-signing-secret-here';

$expected = hash_hmac('sha256', $rawBody, $signingSecret);

if ($expected !== $xSignature) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);

require "openssl"

raw_body       = request.raw_post
x_signature    = request.headers["X-Signature"]
signing_secret = "your-signing-secret-here"

expected = OpenSSL::HMAC.hexdigest("SHA256", signing_secret, raw_body)

raise "Invalid signature" unless expected == x_signature

payload = JSON.parse(raw_body)

Security recommendations

Recommendation

Detail

Use a timing-safe comparison

Always compare signatures using a constant-time function (e.g. hmac.compare_digest, CryptographicOperations.FixedTimeEquals, hash_equals). Standard string equality leaks timing information that attackers can exploit.

Read the raw body

Compute the HMAC over the raw request bytes, before any JSON parsing.

Store secrets in environment variables

Never hardcode your signing_secret in source code. Use environment variables or a dedicated secrets manager.

Rotate secrets if compromised

If you suspect a secret has been exposed, delete the webhook subscription and create a new one to obtain a fresh secret.

Respond promptly

Return a 2xx response as quickly as possible — ideally before doing any heavy processing. Plannr may retry deliveries that do not receive a timely response.

PreviousRate Limits NextAdd-On Store

Last updated 2 days ago

Was this helpful?

hashtagStep 1 — Retrieve your signing secret

hashtagStep 2 — Understand the signature

hashtagStep 3 — Verify the signature

hashtagSecurity recommendations

Step 1 — Retrieve your signing secret

Step 2 — Understand the signature

Step 3 — Verify the signature

Security recommendations