Sign check

Overview

Webhook signature verification allows the merchant system to confirm that a webhook request was sent by Calypso and that the payload was not changed in transit.

Use the same HMAC-SHA512 signing principle as for API requests: calculate the signature from the exact webhook request body and compare it with the Sign header.

Webhook signature headers

Header	Description
Sign	HEX-encoded HMAC-SHA512 signature of the webhook request body.
Key	Public webhook key used to identify the webhook signing key pair.

Where to get webhook keys

Webhook signing keys are returned by webhook subscription methods.

Method	Purpose
[POST] subscription/webhook/create	Create a webhook subscription and receive signing keys.
[POST] subscription/webhook	Get webhook subscriptions and their signing keys.
[POST] subscription/webhook/change	Change a webhook subscription.
[DELETE] subscription/webhook/api-keys/regenerate	Regenerate webhook signing keys.

Verification flow

1. Read the raw webhook request body exactly as it was received.
2. Find the webhook secret key that corresponds to the Key header.
3. Create an HMAC-SHA512 signature using the raw request body as the message and the webhook secret key as the key.
4. Compare the calculated signature with the Sign header.
5. Process the webhook only if the signatures match.

Related docs

Document	Link
API Authentication	API Authentication
Webhook payload	Webhook payload