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

The signature is computed from taskId and the timestamp and does not cover the request body. It verifies that the callback was sent by KIE; for the authoritative result, query Get Task Details with the taskId.

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 data.taskId from the request body (Suno callbacks use data.task_id)

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.

TIP

If the signatures match, the webhook request is confirmed to be from Kie AI's official servers and can be safely processed.

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:

Callback delivery

A callback is sent when a task succeeds and when it fails; check data.state (or code) before reading results.

Callbacks may come from different IP addresses, so verify them with the signature described on this page instead of an IP allowlist.

Respond with an HTTP 2xx status after receiving the callback.

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#

Callback delivery#

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

Callback delivery