Ctrl+K

Register a webhook signing key

post/api/policy/v1/enterprises/{enterpriseId}/webhooks/keys

Registers a new webhook signing key for an enterprise. The key can be provided inline via a JWKS payload or referenced via a JWKS URI.

Key ID selection: The keyId (derived from the kid field in the JWK, or supplied explicitly for JWKS URI registrations) must be unique within the enterprise. Once a keyId is used — even if the key is later revoked — it is permanently tombstoned and cannot be reused. Plan for this by choosing a stable, unique keyId from the start (e.g. my-key-v2).

Recommended rotation workflow:

  1. Register the new key under a new keyId (e.g. my-key-v2).
  2. Update your service configuration to sign webhooks with the new key.
  3. Revoke the old key only after you have confirmed the new key is working.

Authorization: Caller must be an admin of the specified enterprise.

Path Parameters

  • enterpriseIdstringRequired
    The enterprise ID.

Request Body

jwks object
Inline JWKS payload containing the public key(s). Mutually exclusive with jwksUri. The `kid` field inside the JWK object becomes the `keyId` for this registration. Choose a stable, unique `kid` value (e.g. `my-key-v2`) because once a `keyId` is revoked it is permanently tombstoned and cannot be reused.
keys array[object] required
Array of JWK objects. Exactly one key must be provided.
jwksUri string
URI pointing to a hosted JWKS endpoint. Mutually exclusive with jwks.
Example: https://example.com/.well-known/jwks.json
keyId string
Customer-provided key identifier. Required when registering via `jwksUri` (must match the `kid` in your JWKS endpoint). Optional when registering inline JWKS (derived from the JWK `kid` field if not provided). **Permanent restriction:** Once a `keyId` is registered under an enterprise — even if the key is later revoked — the `keyId` is permanently tombstoned and cannot be reused. Attempting to re-register the same `keyId` returns a 400 error. Choose stable, unique values (e.g. `my-key-v2`) to avoid needing to update secrets and configuration after key rotation.
Max length: <= 255 characters
Example: my-key-v2
keyName string
Human-readable name for the key.
Example: Production Webhook Key

201 Response

id string <uuid>required
Internal UUID of the registered key.
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
keyId string required
The derived key identifier.
Example: customer-prod-key-2026
algorithm
string or null
The signing algorithm (EdDSA or ECDSA). Null for JWKS URI registrations.
Allowed values: EdDSA ECDSA
Example: EdDSA
jwksUri
string or null
The JWKS URI if the key was registered via URI.
Example: https://example.com/.well-known/jwks.json
status string required
Status of the newly registered key.
Example: ACTIVE
createdDate string <date-time>required
When the key was registered.
Example: 2026-01-12T10:30:00.000Z

400 Response

One of
code string
message string
status integer

401 Response

code string
message string
status integer

403 Response

code string
message string
status integer

409 Response

code string
message string
status integer

500 Response

code string
message string
status integer