Skip to main content
POST
/
v1
/
webhooks
/
{id}
/
rotate-key
Rotate Webhook Signing Key
curl --request POST \
  --url https://api.example.com/v1/webhooks/{id}/rotate-key \
  --header 'Authorization: <authorization>'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "partner-name",
    "name": "KYC Status Webhook",
    "url": "https://api.partner.com/webhooks/kyc",
    "apiKey": "whk_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4z3y2x1w0v9u8",
    "eventTypes": ["kyc.status.changed"],
    "isActive": true,
    "metadata": {},
    "createdAt": "2025-12-29T10:00:00.000Z",
    "updatedAt": "2025-12-29T14:00:00.000Z"
  }
}

​
Rotate Webhook Signing Key

POST https://api.baanx.com/v1/webhooks/{id}/rotate-key Generates a new API key for webhook signature verification and immediately invalidates the old one.

​
Overview

Use this endpoint when you need to rotate your webhook signing key — for example, if the key has been compromised or as part of a routine key rotation policy.
Immediate invalidation. The old API key is invalidated the moment this endpoint is called. Any in-flight webhooks that were signed with the old key will fail signature verification on your end.Save the new key immediately. The full API key is returned only once and cannot be retrieved again.

​
Authentication

This endpoint requires authentication via Bearer token: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Path Parameters

​
id
string (UUID)
required
Unique identifier of the webhook configuration

​
Request Example

curl -X POST https://api.baanx.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000/rotate-key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
200 Success

Store the apiKey from the response immediately and securely. It will not be shown again.
​
success
boolean
Indicates the key was rotated successfully
​
data.apiKey
string
New full API key — store securely and update your webhook receiver immediately. The old key is now invalid.
​
data
object
Full webhook configuration. See Get Webhook for all field descriptions.
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "partner-name",
    "name": "KYC Status Webhook",
    "url": "https://api.partner.com/webhooks/kyc",
    "apiKey": "whk_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4z3y2x1w0v9u8",
    "eventTypes": ["kyc.status.changed"],
    "isActive": true,
    "metadata": {},
    "createdAt": "2025-12-29T10:00:00.000Z",
    "updatedAt": "2025-12-29T14:00:00.000Z"
  }
}

​
Error Responses

{
  "message": "Not authenticated"
}

​
Key Rotation Checklist

  1. Ensure you have a secure place to store the new key (e.g., a secrets manager)
  2. Notify your team that a rotation is occurring
  3. Be prepared to update your webhook receiver immediately after rotation
  1. Immediately store the new apiKey from the response in your secrets manager
  2. Deploy the new key to your webhook receiver
  3. Verify incoming webhooks are being verified correctly with the new key
  4. Monitor your delivery logs for any signature failures
  • GET /v1/webhooks/{id} - Get current webhook configuration
  • GET /v1/webhooks/{id}/logs - Monitor delivery success after key rotation
  • POST /v1/webhooks - Create a new webhook (also returns a full key)