Usage Info

This method activates a webhook key, making it the current active key for encrypting webhook payloads sent to your endpoints. Only one key can be active at a time per account. When you activate a new key, any previously active key is automatically moved to DELETED status.

Before activating a new key, ensure you have updated your webhook processing infrastructure with the new SharedSecret (obtained from webhook.key.create) and mapped the key_id to the SharedSecret so your system can properly decrypt incoming webhooks.

The activation process is atomic - either the new key is activated and the old key is deactivated, or the operation fails with no changes. This prevents scenarios where you might have zero or multiple active keys.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
key_id	string	Yes	The identifier for the webhook key to activate (format: whk_YYYYMMDD_NN).

Example

{
  "key_id": "whk_20251021_02"
}

Response

Data

Parameter	Type	Description
key_id	string	The identifier for the webhook key that was activated.
status	string	The current status of the key. Must be one of the WEBHOOK_KEY_STATUSES. Will be ACTIVE after successful activation.
activated_at	string	The date-time when the key was activated in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ).

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_7pQfuKPPkHWrMLsiYronG",
    "version": "2025-03-24"
  },
  "data": {
    "key_id": "whk_20251021_02",
    "status": "ACTIVE",
    "activated_at": "2025-10-21T16:30:00.000Z"
  }
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Key ID format is invalid.
ENTITY_NOT_FOUND	400	The `key_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	KEY_ALREADY_ACTIVE	The specified key is already in ACTIVE status.
Webhook Key	KEY_DELETED	Cannot activate a key that has been deleted. Create a new key instead.