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

PHP

Node.js

Python

verify() raises instead of returning a boolean — catch InvalidSignature so the result is the same pass/fail shape as the other examples.
Live deliveries are compact JSON, one line with no whitespace; the samples on Event Types and Payloads are pretty-printed for reading. Verify and parse the bytes you received, never a re-serialised copy.

Test Fixture

Before going live, run your verifier against this fixture. The three pieces belong together: the signature is over exactly the body below, as bytes (387 bytes, no trailing newline). X-Signature header value:
Public key (PEM):
Raw request body:
Expected: your verifier returns true. Change one byte of the body (for example "verified" to "rejected") and it must return false — if it still returns true, the code is not verifying. This key pair exists only for this fixture. It is not a CHIP key, no delivery is ever signed with it, and it must never be used to accept real traffic. Live deliveries are verified against the public_key returned by Retrieve a Webhook.
CHIP is not responsible for any financial losses incurred as a result of failing to implement payload signature verification.