Webhooks

Real-Time Event Processing

Webhooks allow you to build or set up integrations which subscribe to certain events on BillDesq. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.

1. Setting Up Endpoints

You can configure webhook endpoints via your BillDesq Dashboard. Simply provide the URL where you want to receive events and select the types of events you want to subscribe to.

2. Securing Webhooks

To ensure that the webhook requests are actually originating from BillDesq, we sign the webhook events we send to your endpoints by including a signature in each event's BillDesq-Signature header.

// Example using our Node.js SDK to verify
const event = billdesq.webhooks.constructEvent(
  request.body,
  request.headers['billdesq-signature'],
  endpointSecret
);

3. Common Event Types

  • charge.succeeded - Occurs whenever a charge is successful.
  • charge.failed - Occurs whenever a charge attempt fails.
  • customer.subscription.created - Occurs whenever a customer is signed up for a new plan.
  • customer.subscription.deleted - Occurs whenever a customer's subscription ends.
  • invoice.payment_succeeded - Occurs whenever an invoice payment attempt succeeds.

4. Best Practices

Acknowledge receipt of a webhook right away by returning a 200 OK HTTP response. Do not perform complex logic or API calls synchronously within the webhook route; process the event asynchronously instead.