API reference
Create webhook endpoint
Register a receiver. Secret returned once.
POST
/webhooksRegister an HTTPS receiver for one environment. The signing secret is returned once.
- Permission
- write:webhooks
- Auth
- api-key
- Idempotent
- Yes — send Idempotency-Key
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| url | body | string | Yes | HTTPS URL. Private-network and cloud-metadata destinations are rejected. |
| events | body | string[] | No · all | Event types to deliver, or ["*"]. Unknown types return 400. New types are only sent to endpoints that list them or "*". |
| environment | body | string | No | sandbox or production. API keys always use their own environment; the console defaults to production. The endpoint only receives events from that environment. |
| description | body | string | No | Label shown in the console. |
const response = await fetch(`${process.env.BOSPAY_API_BASE}/webhooks`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
"Idempotency-Key": "order-1048-attempt-1",
},
body: JSON.stringify({
"url": "https://merchant.example/webhooks/bospay",
"events": [
"invoice.paid",
"invoice.payment_detected",
"invoice.partial"
],
"description": "Order fulfillment"
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
201
{
"id": "we_example",
"object": "webhook_endpoint",
"url": "https://merchant.example/webhooks/bospay",
"events": [
"invoice.paid",
"invoice.payment_detected",
"invoice.partial"
],
"environment": "sandbox",
"status": "enabled",
"secret": "whsec_… (returned once)"
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}