Usage Info

This method creates a new SharedSecret (encryption key) for securing webhook payloads sent to your endpoints. Each account can have multiple keys, but only one can be active at a time. When you create a new key, it starts in an INACTIVE state and must be explicitly activated using webhook.key.activate.

The SharedSecret is returned in plaintext exactly once during creation - you must store it securely in your infrastructure. This key will be used to encrypt webhook payloads using AES-256-GCM encryption before they are sent to your configured webhook URLs.

Keys are identified using the format whk_YYYYMMDD_NN where YYYYMMDD is the creation date and NN is the iteration number (01-99). There is a maximum of 100 keys per account per day to prevent abuse.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
account_id	string	Yes	The account identifier to create the webhook key for.

Example

{
  "account_id": "lv_4K8mPxR9N2jL7hS5TdWfY1"
}

Response

Data

Parameter	Type	Description
key_id	string	The identifier for the webhook key (format: whk_YYYYMMDD_NN).
shared_secret	string	The Base64-encoded encryption key. Store this securely - it is only returned once.
status	string	The current status of the key. Must be one of the WEBHOOK_KEY_STATUSES. Will be INACTIVE for newly created keys.
created_at	string	The date-time when the key was created in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ).

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_3OwNmn7AgCvLGqeCIjKjSD",
    "version": "2025-03-24"
  },
  "data": {
    "key_id": "whk_20251021_01",
    "shared_secret": "dGhpcyBpcyBhIHRlc3Qgc2VjcmV0IGtleQ==",
    "status": "INACTIVE",
    "created_at": "2025-10-21T15:42:33.109Z"
  }
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Account ID format is invalid.
ENTITY_NOT_FOUND	400	The `account_id` provided does not exist.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Webhook Key	DAILY_LIMIT_EXCEEDED	The maximum number of keys (100) has been reached for this account for the current day.