Overview

Webhook is a mechanism for receiving real-time event notifications, used to transmit data to your application. When we send a webhook notification, a signature is included in the header to ensure the integrity of the notification and the authenticity of its source.

Signature Header

In every event notification, the Signature in the header contains a timestamp and a signature.

The timestamp is prefixed with t=, and the signature is prefixed with v1.

Example:

Webhook Secret

For every event notification, a unique secret key is generated: whsec_.

Before verifying the signature, you need to retrieve your webhook secret, which can be extracted from the secret field within the webhook object.

Verifying Your Signature

By comparing the signature in the header with your locally generated signature, you can verify whether the signature was issued by us.

Follow the guide below step-by-step to verify your signature.

Step 1: Extract Timestamp and Signature from the Header

You can split and extract the signature elements using , as a delimiter. Then, separate the prefix and value of each element using the = sign.

After extraction, the value corresponding to the prefix t is the timestamp, and v1 corresponds to the signature.

Example:

t=1687845304,v1=6fdfb9c357542b8ee07277f5fca2c6f728bae2dce9be2f91412f4de922c1bae4

Step 2: Prepare the `signed_payload` String

The signed_payload string is created by concatenating the following:

The timestamp (as a string)

The character .

The actual JSON payload (i.e., the request body)

You can refer to the format below to prepare the signed_payload string:

1687845304+.+JSON payload

1687845304.{
  "id": "evt_1NNUrjL6kclEVx6Mb1x5dKJ3",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1687845303,
  "data": {
    "object": {
      "id": "prod_O9oUVgsSaordCT",
      "object": "product",
      "active": true,
      "livemode": true,
      "name": "test",
      "type": "service",
  "livemode": true,
  "pending_webhooks": 1,
  "type": "product.created"
}

Step 3: Generate the Local Signature

Calculate the HMAC hash using the SHA256 hash function.

You can obtain your webhook secret from the webhook.secret field in the webhook object. This whsec_ string will serve as the Key for generating the HMAC hash.

Use the signed_payload string prepared in Step 2 as the Message for generating the HMAC hash.

By combining the Key + Message in the SHA256 hash function, you will obtain a string of HMAC characters, which is your local signature.

Example:

Step 4: Compare Local Signature and Signature in Header

Compare the local signature with the signature in the header. Perform an equality check. Additionally, calculate the difference between the timestamp corresponding to created in the webhook object and the timestamp in the signature in the header, then determine if this difference falls within your acceptable tolerance range.

To prevent timing attacks, use a constant-time string comparison method when comparing the local signature with the received signature in the header.

Webhook Signature Verification

Overview#

Signature Header#

Webhook Secret#

Verifying Your Signature#

Step 1: Extract Timestamp and Signature from the Header#

Step 2: Prepare the signed_payload String#

Step 3: Generate the Local Signature#

Step 4: Compare Local Signature and Signature in Header#

Overview

Signature Header

Webhook Secret

Verifying Your Signature

Step 1: Extract Timestamp and Signature from the Header

Step 2: Prepare the `signed_payload` String

Step 3: Generate the Local Signature

Step 4: Compare Local Signature and Signature in Header