Webhooks
Receive events
Validate the raw bytes, persist the event, then acknowledge. Fulfill from invoice.paid.
Create an endpoint
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();Handle
- Read x-bospay-timestamp, x-bospay-signature, and the raw body.
- Verify HMAC-SHA256(secret, timestamp + "." + rawBody) with a timing-safe compare. The header can hold several comma-separated signatures during a secret rotation; accept if any matches.
- Reject timestamps outside a five-minute window.
- Persist the event id (also sent as x-bospay-event-id) with a unique constraint, enqueue work, and return 2xx within 10 seconds.
- GET the invoice and fulfill once when status is paid.
- Create one endpoint per environment. A sandbox endpoint never receives live events.