Webhooks

Webhooks allow your application to receive real-time notifications about events that occur in your Billingrails application. By setting up webhooks you can:

• Keep your application in sync with Billingrails
• Sync information with other third-party services that your business uses
• Set up automation workflows based on specific events

Webhook events

Webhook events are specific occurrences within your Billingrails account that can trigger a webhook notification. When configuring a webhook destination, you can subscribe to all events or choose specific events by resource and action.

Available events

You can subscribe to every event (*), all events for a resource (e.g. order.*), or individual events (e.g. order.paid).

Webhook destinations

A webhook destination is the URL endpoint where webhook notifications are sent. This is typically an endpoint in your application that is set up to receive and process webhook payloads. Billingrails allows you to configure up to 10 endpoints per site.

Creating a webhook destination

1. In the dashboard, go to Developers → Webhooks → Configure webhook destination → Create destination.
2. Enter the Destination URL — the HTTPS endpoint that will receive webhook payloads (e.g. https://yoursite.com/incoming_webhook).
3. Optionally add a Description to identify this destination (e.g. "Production order notifications").
4. Optionally set a Secret key — used to sign payloads so you can verify requests with HMAC-SHA256. If you leave it blank, no signature is sent.
5. Choose Subscribed events: select All events to receive every event, or expand the list and select specific resources (Account, Invoice, Order, Payment, Subscription) and individual events (e.g. order.paid, invoice.issued).
6. Turn Active on to start receiving webhooks, or leave it off to save the destination without enabling delivery.
7. Click Create destination to save.

You can edit or deactivate a destination at any time from the same Webhooks area.

A webhook counts as delivered when Billingrails receives a successful (2xx) response from your endpoint. If a webhook fails to deliver (non-2xx response or timeout), Billingrails will retry the delivery up to 3 times with exponential backoff.

Webhook signatures

Billingrails signs webhook payloads using HMAC-SHA256 with the secret key configured in your webhook destination. The Base64-encoded signature is sent in the x-billingrails-signature header. If no secret key is configured, no signature is sent. To verify a webhook:

const crypto = require('crypto');

const receivedSignature = req.headers['x-billingrails-signature'];
const secretKey = 'your_webhook_destination_secret_key';
const rawBody = JSON.stringify(req.body);

const computedHmac = crypto
  .createHmac('sha256', secretKey)
  .update(rawBody)
  .digest('base64');

if (computedHmac === receivedSignature) {
  // Valid - process webhook
} else {
  // Invalid - reject request
  return res.status(401).send('Invalid signature');
}