Webhooks
Create a webhook endpoint
POST
/webhook-endpointsScope
webhooks:writeAuth Bearer keyIdempotentThe signing secret is returned once, in this response. Verify deliveries with the BoundlessPay-Signature header (t=<unix>,v1=<hex HMAC-SHA256 of `${t}.${body}`>).
Headers
Idempotency-KeystringrequiredRetrying with the same key and payload replays the original response.
Request body
json
{
"url": "https://merchant.example.com/hooks/boundlesspay",
"description": "Production ledger sync",
"enabled_events": [
"transfer.completed",
"transfer.failed",
"deposit.settled"
]
}Responses
201Endpoint with signing secret
json
{
"id": "whe_6d21c9f0a3b7",
"object": "webhook_endpoint",
"url": "https://merchant.example.com/hooks/boundlesspay",
"description": "Production ledger sync",
"environment": "live",
"enabled_events": [
"transfer.completed",
"transfer.failed",
"deposit.settled"
],
"status": "active",
"consecutive_failures": 0,
"last_success_at": "2026-08-30T09:15:02.441Z",
"last_failure_at": null,
"last_error": null,
"created_at": "2026-07-04T11:02:19.006Z",
"signing_secret": "whsec_9c1f0f8a4c2d47bb9a3e5f7d1b0c8e26"
}Errors
Errors use RFC 9457 problem details. Branch on code, and log request_id.
400Bad request401Unauthenticated403Forbidden409Idempotency conflict422Validation error429Rate limitedcURL
curl -X POST "https://business.boundlesspay.com/api/public/v1/webhook-endpoints" \
-H "Authorization: Bearer $BOUNDLESS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "url": "https://merchant.example.com/hooks/boundlesspay", "description": "Production ledger sync", "enabled_events": [ "transfer.completed", "transfer.failed", "deposit.settled" ] }'