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. Examples of webhook events include:

• Customer created
• Subscription updated
• Invoice paid
• Payment failed

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.

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');
}