Sign in
latestOpenAPI 3.0.32026-08-224982,0272.8 MB

e445c15e5bee

Webhook Keys

Register a webhook signing key

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.

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

Path parameters

enterpriseIdstring required

The enterprise ID.

Headers

X-BitGo-OTPstring required

OTP code for verification. Required for webhook key management operations.

Request body

jwksUristring

URI pointing to a hosted JWKS endpoint. Mutually exclusive with jwks.

keyIdstring

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.

keyNamestring

Human-readable name for the key.

Example request

{
  "jwksUri": "https://example.com/.well-known/jwks.json",
  "keyId": "my-key-v2",
  "keyName": "Production Webhook Key"
}

Response

Key successfully registered.

idstring uuid required

Internal UUID of the registered key.

keyIdstring required

The derived key identifier.

algorithm'EdDSA' | 'ECDSA' nullable

The signing algorithm (EdDSA or ECDSA). Null for JWKS URI registrations.

jwksUristring nullable

The JWKS URI if the key was registered via URI.

statusstring required

Status of the newly registered key.

createdDatestring date-time required

When the key was registered.

Example response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "keyId": "customer-prod-key-2026",
  "algorithm": "EdDSA",
  "jwksUri": "https://example.com/.well-known/jwks.json",
  "status": "ACTIVE",
  "createdDate": "2026-01-12T10:30:00.000Z"
}