1. Overview

Webhooks allow BOOST (and its billing provider) to notify your systems when important events occur, such as subscription changes, plan updates, or usage thresholds. Instead of polling APIs, your backend receives signed HTTP requests whenever something relevant happens.

Webhooks are for servers you control. Never expose webhook endpoints directly to browsers or untrusted clients. Not legal advice. Not financial advice.

2. Typical webhook use cases

Common scenarios where webhooks are useful include:

• Updating a local record when a BOOST subscription is created, upgraded, downgraded, or canceled.
• Adjusting access when a plan changes (for example, enabling more tools or higher limits).
• Recording usage-related events when you need an internal audit log of plan changes and limit-related behavior.

Webhooks do not carry client or listing content. They are focused on account, plan, and usage signals, not property or demographic data.

3. Webhook endpoint requirements

To receive webhooks from BOOST or its billing provider, your endpoint must:

• Be reachable over HTTPS.
• Accept POST requests with a JSON body.
• Return a 2xx status code when the event is processed successfully.
• Always verify the request signature before trusting the payload.

Endpoints should respond quickly and avoid long-running tasks; schedule background work if needed to keep response times low and reduce retries.

4. Event types

The exact event types depend on your billing configuration, but representative examples include:

• subscription.created – a new subscription or plan is started.
• subscription.updated – plan, status, or limits are changed.
• subscription.canceled – a subscription has ended.
• invoice.paid – an invoice has been successfully paid.
• invoice.payment_failed – payment for an invoice failed.
• usage.threshold_reached – a usage threshold associated with a plan or tool has been crossed.

{
  "id": "evt_123",
  "type": "subscription.updated",
  "created": "2025-01-01T12:00:00Z",
  "data": {
    "accountId": "acct_456",
    "plan": "pro-bundle-example",
    "status": "active"
  }
}

5. HMAC signatures and verification

Every webhook request will include a signature header so your server can verify that the request was sent by BOOST (or its billing provider) and not forged. This is typically implemented using an HMAC (hash-based message authentication code).

At a high level, verification works as follows:

1. BOOST computes a signature using a shared secret and the raw request body, for example:
   • algorithm: HMAC-SHA256
   • input: the exact JSON payload bytes
   • key: your webhook secret
2. The resulting digest is included in an HTTP header (for example, X-Boost-Signature).
3. Your server recomputes the HMAC using the same algorithm and secret and compares it to the header value using a constant-time comparison.
4. If they match, the payload can be trusted; if not, you should reject the request.

const signatureHeader = req.headers["x-boost-signature"];
const rawBody = getRawRequestBody(req);
const expected = hmacSha256(WEBHOOK_SECRET, rawBody);

if (!timingSafeEqual(signatureHeader, expected)) {
  // Reject: signature does not match
  return res.status(400).send("Invalid signature");
}

// Process event safely

Always use the raw request body for HMAC verification, not a parsed or re-serialized version, to avoid subtle mismatches.

6. Retries and idempotency

If your endpoint does not return a 2xx status code, the webhook delivery system may retry the event after a delay. To handle retries safely:

• Treat each event as idempotent: processing the same event more than once should not cause duplicate side effects.
• Use the event id field to track whether an event has already been processed.
• Return a 2xx response only after your system has successfully handled the event.

if (hasSeenEvent(event.id)) {
  // Already processed; return success to stop retries
  return res.status(200).send("OK");
}

markEventAsProcessed(event.id);
// Apply changes based on event.data...
return res.status(200).send("OK");

7. Security best practices

When configuring webhook endpoints for BOOST:

• Use HTTPS with a valid certificate; do not accept webhooks over plain HTTP.
• Keep your webhook secret out of source control and logs.
• Verify HMAC signatures on every request before parsing or acting on the payload.
• Restrict the endpoint path to webhook use only; do not reuse it for general APIs or public forms.
• Log failures and unusual patterns (for example, repeated invalid signatures) to investigate potential misuse.

Webhooks convey billing and usage state, not legal or demographic information. Fair Housing/CREA compliant; no protected-class criteria used. Not legal advice. Not financial advice.

8. Relationship to billing & limits

Webhooks complement your views in the BOOST app and billing portal. They do not replace those interfaces, but they help you keep external systems synchronized.

• Subscription changes sent via webhooks should match the status shown in Billing & Subscription.
• Usage-related events may signal when you are approaching or surpassing limits described in Usage limits & rate limiting.
• You should still treat your billing provider's official statements and invoices as the source of truth for charges and tax records.

9. Troubleshooting webhook issues

If you believe webhooks are not working correctly, check the following:

• Confirm the endpoint URL is correct and reachable from the public internet.
• Ensure your server accepts POST requests with a JSON body at that path.
• Check that you are returning a 2xx status code on success.
• Verify that your HMAC logic uses the raw request body and the correct shared secret; log both your computed signature and the incoming header for debugging (without logging the secret).
• Inspect server logs for recent errors or timeouts around the time events were sent.

When in doubt, temporarily log incoming payload IDs and types (without sensitive secrets) to confirm that webhooks are arriving and being parsed as expected.