Webhooks

Overview

BoxBilling sends webhook notifications when key events occur. Webhooks are delivered as HTTP POST requests with JSON payloads to your configured endpoints.

Setting up webhooks

Create a webhook endpoint

curl -X POST /v1/webhook_endpoints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/boxbilling",
    "signature_algo": "hmac"
  }'

You can create multiple endpoints — each will receive all webhook events.

Endpoint properties

Field	Type	Description
id	uuid	Unique endpoint identifier
url	string	Delivery URL (max 2048 chars)
signature_algo	string	Signature algorithm (default: hmac)
status	string	Endpoint status (active, inactive)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Update an endpoint

You can update the URL, signature algorithm, or status of an existing endpoint:

curl -X PUT /v1/webhook_endpoints/{endpoint_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/v2",
    "status": "active"
  }'

List endpoints

curl /v1/webhook_endpoints \
  -H "Authorization: Bearer $API_KEY"

Supports skip, limit, and order_by query parameters.

Webhook events

Invoice events

Event	Trigger
invoice.created	New invoice generated
invoice.finalized	Invoice finalized and ready for payment
invoice.paid	Invoice fully paid
invoice.voided	Invoice voided

Payment events

Event	Trigger
payment.created	Payment record created
payment.succeeded	Payment completed successfully
payment.failed	Payment failed

Subscription events

Event	Trigger
subscription.created	New subscription created
subscription.started	Subscription activated
subscription.plan_changed	Plan upgrade or downgrade applied
subscription.trial_ended	Trial period expired
subscription.canceled	Subscription canceled
subscription.terminated	Subscription terminated

Customer events

Event	Trigger
customer.created	New customer created
customer.updated	Customer record updated

Credit note events

Event	Trigger
credit_note.created	Credit note created
credit_note.finalized	Credit note finalized

Wallet events

Event	Trigger
wallet.created	Wallet created
wallet.terminated	Wallet terminated
wallet.transaction.created	Wallet transaction recorded

Usage events

Event	Trigger
usage_threshold.crossed	Usage threshold exceeded

Payment request events

Event	Trigger
payment_request.created	Dunning payment request created
payment_request.payment_succeeded	Dunning payment succeeded
payment_request.payment_failed	Dunning payment failed

Webhook response properties

Each webhook delivery record contains full details about the event and delivery status:

Field	Type	Description
id	uuid	Unique webhook ID
webhook_endpoint_id	uuid	Target endpoint
webhook_type	string	Event type (e.g. invoice.finalized)
object_type	string	Entity type (e.g. invoice)
object_id	uuid	Entity UUID
payload	object	Full event payload
status	string	Delivery status (pending, succeeded, failed)
retries	integer	Current retry count
max_retries	integer	Maximum retry limit
last_retried_at	datetime	Last retry timestamp
http_status	integer	HTTP response code from endpoint
response	string	Response body from endpoint
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Payload format

{
  "webhook_type": "invoice.finalized",
  "object_type": "invoice",
  "object_id": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoice_number": "INV-20250115-0001",
    "status": "finalized",
    "total": 9900,
    "currency": "USD"
  }
}

Signature verification

Every webhook includes signature headers for verification:

Header	Description
X-Bxb-Signature	HMAC-SHA256 hex digest of the payload
X-Bxb-Signature-Algorithm	Signature algorithm (default: hmac)
X-Bxb-Webhook-Id	Unique webhook delivery ID

Verifying signatures

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Retry logic

Failed webhook deliveries are automatically retried with exponential backoff:

Retry	Delay
1st	2 minutes
2nd	4 minutes
3rd	8 minutes
4th	16 minutes
5th	32 minutes

Formula: delay = 2^retries minutes

The retry task runs every 5 minutes. After the maximum number of retries (default: 5), the webhook is marked as permanently failed.

Webhook statuses

Status	Description
pending	Queued for delivery
succeeded	Delivered successfully (2xx response)
failed	Delivery failed after all retries

Delivery attempts

Each delivery attempt is tracked individually with its own response details:

Field	Type	Description
id	uuid	Delivery attempt ID
webhook_id	uuid	Parent webhook
attempt_number	integer	Sequential attempt number
http_status	integer	HTTP response code
response_body	string	Response body text
success	boolean	Whether the attempt succeeded
error_message	string	Error details if failed
attempted_at	datetime	When the attempt was made

View delivery attempts

curl /v1/webhook_endpoints/hooks/{webhook_id}/delivery_attempts \
  -H "Authorization: Bearer $API_KEY"

Returns all delivery attempts for a webhook, ordered by attempt number.

Delivery statistics

Get aggregate delivery stats per endpoint to monitor webhook health:

curl /v1/webhook_endpoints/delivery_stats \
  -H "Authorization: Bearer $API_KEY"

Response:

[
  {
    "endpoint_id": "endpoint-uuid",
    "total": 1250,
    "succeeded": 1200,
    "failed": 50,
    "success_rate": 96.0
  }
]

Field	Type	Description
endpoint_id	string	Webhook endpoint ID
total	integer	Total deliveries
succeeded	integer	Successful deliveries
failed	integer	Failed deliveries
success_rate	number	Success percentage

Monitoring webhooks

List webhook deliveries

curl "/v1/webhook_endpoints/hooks/list?status=failed" \
  -H "Authorization: Bearer $API_KEY"

Supports skip, limit, webhook_type, and status query filters.

Retry a failed webhook

curl -X POST /v1/webhook_endpoints/hooks/{webhook_id}/retry \
  -H "Authorization: Bearer $API_KEY"

Only webhooks with failed status can be retried.

Payment provider webhooks

BoxBilling also receives inbound webhooks from payment providers to update payment and invoice status:

POST /v1/payments/webhook/{provider}

Supported providers: stripe, manual, ucp, gocardless, adyen

Each provider uses its own signature header for verification:

Provider	Signature Header
Stripe	Stripe-Signature
UCP	X-UCP-Signature
Others	Webhook-Signature

Note

Payment provider webhook endpoints are configured in your provider dashboard, not through the BoxBilling webhook endpoint API.

API endpoints

Webhook endpoint management

Method	Path	Description
POST	/v1/webhook_endpoints	Create endpoint
GET	/v1/webhook_endpoints	List endpoints
GET	/v1/webhook_endpoints/{id}	Get endpoint
PUT	/v1/webhook_endpoints/{id}	Update endpoint
DELETE	/v1/webhook_endpoints/{id}	Delete endpoint

Webhook deliveries

Method	Path	Description
GET	/v1/webhook_endpoints/hooks/list	List deliveries
GET	/v1/webhook_endpoints/hooks/{id}	Get delivery details
GET	/v1/webhook_endpoints/hooks/{id}/delivery_attempts	Get delivery attempts
POST	/v1/webhook_endpoints/hooks/{id}/retry	Retry a delivery
GET	/v1/webhook_endpoints/delivery_stats	Get delivery stats per endpoint

Payment provider webhooks

Method	Path	Description
POST	/v1/payments/webhook/{provider}	Handle inbound payment provider webhook