Skip to main content
POST
/
api
/
canary
/
webhook-endpoints
Registers a URL to receive real-time events (e.g., checkout.session.completed, purchase.succeeded).

​
Request Body

​
url
string
required
The webhook endpoint URL where events will be sent
​
events
array of strings
required
Array of event types to subscribe to (e.g., [“checkout.session.completed”, “payment.succeeded”])
​
active
boolean
Whether the webhook endpoint is active (default: true)
​
metadata
object
Custom metadata to attach to the webhook endpoint

​
Response

​
Webhook Endpoint Created
​
id
string
Unique identifier for the webhook endpoint
​
merchantId
string
The merchant’s unique identifier
​
url
string
The webhook endpoint URL
​
events
array
Array of subscribed event types
​
active
boolean
Whether the endpoint is active
​
metadata
object
Custom metadata
​
createdAt
string
ISO 8601 timestamp when the endpoint was created
​
updatedAt
string
ISO 8601 timestamp when the endpoint was last updated

​
Example Request

{
  "url": "https://example.com/webhooks",
  "events": [
    "checkout.session.completed",
    "purchase.succeeded",
    "transfer.completed"
  ],
  "active": true,
  "metadata": {}
}

​
Example Response

{
  "id": "webhook_001",
  "merchantId": "merchant_456",
  "url": "https://example.com/webhooks",
  "events": [
    "checkout.session.completed",
    "purchase.succeeded",
    "transfer.completed"
  ],
  "active": true,
  "metadata": {},
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

​
Error Responses

​
Bad Request
Invalid request body
​
Unauthorized
Invalid or missing authentication token
​
Internal Server Error
An unexpected error occurred on the server

​
Authentication

This endpoint requires Bearer token authentication.