Webhook signatures

Payloads are signed using asymmetric (public-key) cryptography to guarantee the authenticity of delivered callbacks. Each callback delivery request includes an X-Signature header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA-256 digest of the request body buffer. You can obtain the public key for Webhook authentication from Webhook.public_key of the corresponding Webhook. You can obtain the public key for success callback authentication from GET /public_key/. Please note that CHIP is not responsible for any financial losses incurred as a result of failing to implement payload signature verification.

How to verify

The verification process is:

Read the raw request body (before JSON parsing). The signature is computed over the bytes as received.
Decode the X-Signature header from base64.
Verify it against the request body using the public key with RSA PKCS#1 v1.5 padding and a SHA-256 digest.
Reject the request if verification fails.

Always verify the raw request body. Re-serializing the parsed JSON will change byte ordering or whitespace and break the signature.

Example (Node.js)

const crypto = require('crypto');
const express = require('express');

const app = express();

// IMPORTANT: capture the raw body before any JSON parsing
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; }
}));

app.post('/webhook', async (req, res) => {
  const signature = req.header('X-Signature'); // base64-encoded
  const publicKeyPem = await getPublicKeyForThisWebhook();

  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(req.rawBody);
  verifier.end();

  const ok = verifier.verify(publicKeyPem, signature, 'base64');
  if (!ok) {
    return res.status(401).send('Invalid signature');
  }

  // Signature valid — process the event
  console.log('Verified event:', req.body);
  res.status(200).end();
});

Example (PHP)

$signature = base64_decode($_SERVER['HTTP_X_SIGNATURE']);
$rawBody   = file_get_contents('php://input');

$publicKeyPem = getPublicKeyForThisWebhook(); // PEM-encoded

$ok = openssl_verify($rawBody, $signature, $publicKeyPem, OPENSSL_ALGO_SHA256);
if ($ok !== 1) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature valid — process the event

Example (Python)

import base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def verify(raw_body: bytes, signature_b64: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    signature = base64.b64decode(signature_b64)
    try:
        public_key.verify(
            signature,
            raw_body,
            padding.PKCS1v15(),
            hashes.SHA256(),
        )
        return True
    except Exception:
        return False

Overview

Integrate with AI agents

API Reference

Webhook signatures

How to verify

Example (Node.js)

Example (PHP)

Example (Python)

​How to verify

​Example (Node.js)

​Example (PHP)

​Example (Python)

How to verify

Example (Node.js)

Example (PHP)

Example (Python)