Developers
Webhook Notifications
Asynchronous event notifications for payment lifecycle and settlement events.
Overview
Overview
BoxCharge delivers signed webhook events for payment status changes, refunds, chargebacks, and settlement updates. Each event is signed with HMAC SHA-256 for verification.
Integration
Integration Flow
1. Configure URL
Register your endpoint and event subscriptions.
2. Receive Event
BoxCharge POSTs a signed JSON payload.
3. Verify + Act
Verify the signature, then update internal state.
Sample
Request / Response
POST {your-webhook-url}
POST /your-webhook-endpoint
X-BX-Signature: sha256=...
Content-Type: application/json
{
"event": "payment.authorized",
"id": "evt_98b3...",
"data": {
"payment_id": "pay_8f2c...",
"status": "authorized",
"amount": 12480,
"currency": "EUR"
},
"created_at": "2026-05-25T08:42:11Z"
}Authentication
Signed payloads using a per-merchant secret. Optional mutual TLS available on request.
Security Notes
- • Always verify the X-BX-Signature header before processing.
- • Respond with 2xx within 5 seconds to acknowledge receipt.
- • Implement idempotent handlers — events may be retried.
Notes
Implementation Notes
- • Store the latest event ID per resource to handle out-of-order delivery.
- • Use a queue to decouple webhook receipt from downstream processing.
- • Subscribe only to events you need.
FAQ
Developer FAQ
Failed deliveries are retried with exponential backoff over a defined window.