Skip to main content
POST
/
v1
/
webhooks
Create Webhook Endpoint
curl --request POST \
  --url https://api.example.com/v1/webhooks \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "event_types": [
    {}
  ],
  "is_active": true,
  "metadata": {}
}
'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "partner-name",
    "name": "KYC Status Updates",
    "url": "https://api.partner.com/webhooks/kyc",
    "apiKey": "whk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
    "eventTypes": ["kyc.status.changed"],
    "isActive": true,
    "metadata": {},
    "createdAt": "2025-12-29T10:00:00.000Z",
    "updatedAt": "2025-12-29T10:00:00.000Z"
  }
}

​
Create Webhook Endpoint

POST https://api.baanx.com/v1/webhooks Creates a new webhook configuration for receiving event notifications.

​
Overview

Registers a new HTTPS endpoint to receive webhook deliveries. Each webhook can subscribe to one or more event types and is assigned a unique signing key for signature verification.
Save the API key immediately. The full API key is returned only at creation time and cannot be retrieved again. If lost, use the Rotate Key endpoint to generate a new one.
Limits and defaults:
  • Maximum of 5 webhook endpoints per partner
  • New webhooks are created with is_active: false by default unless explicitly set
  • Only HTTPS URLs are accepted

​
Signature Verification

All webhook deliveries include HMAC-SHA256 signature headers:
HeaderDescription
X-TimestampUnix timestamp of the request
X-SignatureHMAC-SHA256 signature of {timestamp}.{body}
Verify webhooks by computing: 
HMAC-SHA256(apiKey, "{timestamp}.{body}")

​
Authentication

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

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication
​
Content-Type
string
required
Must be application/json

​
Body

​
name
string
required
Human-readable name for the webhook (max 255 characters)
​
url
string
required
HTTPS endpoint URL for webhook delivery. Must use HTTPS.
​
event_types
array
required
Array of event type strings to subscribe to. Must contain at least one item.Available event types:
  • kyc.status.changed - User KYC verification status changed
  • card.activated - Card has been activated
  • transaction.cleared - Transaction has been cleared
​
is_active
boolean
default:false
Whether to activate the webhook immediately. Defaults to false.
​
metadata
object
Optional custom metadata to attach to the webhook (e.g., environment tags)

​
Request Examples

curl -X POST https://api.baanx.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "KYC Status Updates",
    "url": "https://api.partner.com/webhooks/kyc",
    "event_types": ["kyc.status.changed"],
    "is_active": true
  }'

​
Response

​
201 Created

Store the apiKey from the response immediately and securely. It will not be shown again.
​
success
boolean
Indicates the webhook was created successfully
​
data.id
string (UUID)
Unique identifier for the new webhook
​
data.apiKey
string
Full API key — store securely. Used to verify webhook signatures. Not retrievable after this response.
​
data.eventTypes
array
Event types the webhook is subscribed to
​
data.isActive
boolean
Whether the webhook is active
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "partner-name",
    "name": "KYC Status Updates",
    "url": "https://api.partner.com/webhooks/kyc",
    "apiKey": "whk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
    "eventTypes": ["kyc.status.changed"],
    "isActive": true,
    "metadata": {},
    "createdAt": "2025-12-29T10:00:00.000Z",
    "updatedAt": "2025-12-29T10:00:00.000Z"
  }
}

​
Error Responses

{
  "message": "Maximum webhook limit (5) reached for this tenant"
}

​
Common Error Scenarios

Error: 400 Bad RequestMessage: "Maximum webhook limit (5) reached for this tenant"Cause: You already have 5 webhook endpoints configured.Solution: Delete an existing webhook with DELETE /v1/webhooks/{id} before creating a new one.
Error: 400 Bad RequestCause: The url field does not use the HTTPS scheme.Solution: Ensure your endpoint URL begins with https://.
  • GET /v1/webhooks - List all webhook endpoints
  • PUT /v1/webhooks/{id} - Update a webhook configuration
  • POST /v1/webhooks/{id}/rotate-key - Rotate the signing key
  • DELETE /v1/webhooks/{id} - Delete a webhook endpoint