Skip to main content
To ensure that the webhook notifications you receive are sent by CHIP and have not been tampered with, you should validate the signature included in each request.

​
Signature Header

Each webhook delivery request includes an X-Signature header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA512 digest of the request body buffer.

​
Obtaining the Public Key

Unlike CHIP Collect, CHIP Send provides a dedicated public key for each webhook. You can obtain the public key by retrieving the webhook details via the Retrieve a Webhook API. The public_key field in the response contains the PEM-encoded RSA public key.

​
Verification Steps

  1. Retrieve the Payload: Get the raw request body (buffer) of the webhook notification.
  2. Get the Signature: Extract the value of the X-Signature header and base64-decode it.
  3. Verify: Use the RSA public key to verify the signature against the SHA512 digest of the raw request body.

​
Code Examples

​
Ruby

require 'openssl'
require 'base64'

# webhook_public_key: The PEM-encoded public key from the Webhook object
# x_signature_header: The value of the X-Signature header
# request_body: The raw JSON body of the request

public_key = OpenSSL::PKey::RSA.new(webhook_public_key)
signature = Base64.decode64(x_signature_header)
digest = OpenSSL::Digest::SHA512.new

is_valid = public_key.verify(digest, signature, request_body)

if is_valid
  puts "Signature is valid"
else
  puts "Signature is invalid"
end

​
PHP

<?php

// $webhook_public_key: The PEM-encoded public key from the Webhook object
// $x_signature_header: The value of the X-Signature header
// $request_body: The raw JSON body of the request

$public_key = openssl_pkey_get_public($webhook_public_key);
$signature = base64_decode($x_signature_header);

$is_valid = openssl_verify($request_body, $signature, $public_key, OPENSSL_ALGO_SHA512);

if ($is_valid === 1) {
    echo "Signature is valid";
} elseif ($is_valid === 0) {
    echo "Signature is invalid";
} else {
    echo "Error checking signature";
}
The provider is not responsible for any financial losses incurred due to not implementing payload signature verification.