POST

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:

Register the new key under a new keyId (e.g. my-key-v2).
Update your service configuration to sign webhooks with the new key.
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 Params

enterpriseId string required

The enterprise ID.

Header Params

X-BitGo-OTP string required

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

Body Params

object

Request to register a new webhook signing key.

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.
jwks object
- keys array of objects required
  
  Array of JWK objects. Exactly one key must be provided.
jwksUri string

URI pointing to a hosted JWKS endpoint. Mutually exclusive with jwks.
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.

up to 255 characters
keyName string

Human-readable name for the key.

Responses

201

Key successfully registered.

Response Body

object

Response after successfully registering a webhook signing key.

id string uuid required

Internal UUID of the registered key.
keyId string required

The derived key identifier.
algorithm string enum nullable

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

EdDSAECDSA
jwksUri string nullable

The JWKS URI if the key was registered via URI.
status string required

Status of the newly registered key.
createdDate string date-time required

When the key was registered.

400

Bad Request

Response Body

ONE OF

code string
message string
status integer

code string
message string
status integer
failedValidations object

401

Unauthorized

Response Body

object

code string
message string
status integer

403

Forbidden

Response Body

object

code string
message string
status integer

409

Conflict - The request conflicts with the current state of the resource

Response Body

object

code string
message string
status integer

500

Server Error - Transient error please try again

Response Body

object

code string
message string
status integer

curl --request POST \ --url 'https://app.bitgo-test.com/api/policy/v1/enterprises/enterpriseId/webhooks/keys' \ --header 'accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-BitGo-OTP: string' \ --header 'content-type: application/json' \ --data '{,"jwks":{,"keys":[{}]},"jwksUri":"https://example.com/.well-known/jwks.json","keyId":"my-key-v2","keyName":"Production Webhook Key"}'

require 'uri' require 'net/http' url = URI("https://app.bitgo-test.com/api/policy/v1/enterprises/enterpriseId/webhooks/keys") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["accept"] = 'application/json' request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN' request["X-BitGo-OTP"] = 'string' request["content-type"] = 'application/json' request.body = '{,"jwks":{,"keys":[{}]},"jwksUri":"https://example.com/.well-known/jwks.json","keyId":"my-key-v2","keyName":"Production Webhook Key"}' response = http.request(request) puts response.read_body

<?php require_once('vendor/autoload.php'); $client = new \GuzzleHttp\Client(); $response = $client->request('POST', 'https://app.bitgo-test.com/api/policy/v1/enterprises/enterpriseId/webhooks/keys', [ 'headers' => [ 'accept' => 'application/json', 'Authorization' => 'Bearer YOUR_ACCESS_TOKEN', 'X-BitGo-OTP' => 'string', 'content-type' => 'application/json', ], 'body' => '{,"jwks":{,"keys":[{}]},"jwksUri":"https://example.com/.well-known/jwks.json","keyId":"my-key-v2","keyName":"Production Webhook Key"}', ]); echo $response->getBody();

import requests url = "https://app.bitgo-test.com/api/policy/v1/enterprises/enterpriseId/webhooks/keys" payload = {,"jwks":{,"keys":[{}]},"jwksUri":"https://example.com/.well-known/jwks.json","keyId":"my-key-v2","keyName":"Production Webhook Key"} headers = { "accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN", "X-BitGo-OTP": "string", "content-type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text)

{ "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:00Z" }