Webhook Security Verification

To ensure the security of callback requests, it is strongly recommended to enable Webhook HMAC signature verification in production environments to prevent forged requests and replay attacks.

Algorithm Overview

Kie AI uses the HMAC-SHA256 algorithm to generate signatures, ensuring the integrity and authenticity of webhook callbacks.

Signature Generation Process:

Concatenate the data to sign: taskId + "." + timestampSeconds

taskId: Task ID from the request body

timestampSeconds: Unix timestamp in seconds from the X-Webhook-Timestamp header

Calculate HMAC-SHA256 signature:

signature = HMAC-SHA256(dataToSign, webhookHmacKey)

Base64 encode the signature:

finalSignature = Base64.encode(signature)

Obtain Webhook HMAC Key

You can generate and view your webhookHmacKey on the Kie AI Settings Page.

The webhookHmacKey is used to verify that callback requests originate from Kie AI's official servers. Keep this key secure and never expose it or commit it to code repositories.

Webhook Header Description

When you enable the webhookHmacKey feature in the settings page, all callback requests will include the following fields in the HTTP headers:

`X-Webhook-Timestamp`

Type: Integer

Required: Yes

Description: Unix timestamp (in seconds) when the callback request was sent.

`X-Webhook-Signature`

Type: String

Required: Yes

Description: Signature generated using the HMAC-SHA256 algorithm with Base64 encoding.

Signature generation rule:

base64(HMAC-SHA256(taskId + "." + timestamp, webhookHmacKey))

Where:

taskId is the task ID from the callback body

timestamp is the value of X-Webhook-Timestamp

webhookHmacKey is the key you generated in the console

Webhook Verification Process

Follow these steps to verify the legitimacy of webhook requests:

Read Header Fields

Extract the X-Webhook-Timestamp and X-Webhook-Signature fields from the HTTP headers.

Generate Signature

Using your locally stored webhookHmacKey, generate the HMAC-SHA256 signature following these rules:

Extract task_id from the request body

Concatenate the string: taskId + "." + timestamp

Generate signature using HMAC-SHA256 algorithm with webhookHmacKey

Base64 encode the signature result

Compare Signatures

Compare the computed signature with X-Webhook-Signature using a constant-time comparison algorithm to prevent timing attacks.

Complete Example Code

Here are complete examples of implementing webhook signature verification in popular programming languages:

Node.js

Python

PHP

Java

Example Webhook Request

Here's what a complete webhook request looks like:

Webhook Security Verification

Algorithm Overview#

Obtain Webhook HMAC Key#

Webhook Header Description#

X-Webhook-Timestamp#

X-Webhook-Signature#

Signature generation rule:#

Webhook Verification Process#

Complete Example Code#

Example Webhook Request#

Algorithm Overview

Obtain Webhook HMAC Key

Webhook Header Description

`X-Webhook-Timestamp`

`X-Webhook-Signature`

Signature generation rule:

Webhook Verification Process

Complete Example Code

Example Webhook Request