Webhooks

The webhooks feature lets Billingbooth users push information out to third-party systems. This allows events such as invoice creation, settling and voiding be visible in other applications such as ERP and CRM systems.

Endpoints

An account can have one or more webhook endpoints. These define target destinations that Billingbooth will push the events to and are typically HTTP or HTTPS URLs, e.g. https://myevents.domain.com.

To configure a new endpoint, go to Settings > Webhooks > Endpoints. In the create page, you can enter the URL of the site that will receive the webhooks, this should typically be using HTTP or HTTPS. We recommend using HTTPS where possible for secure communication.

An endpoint can receive to one or more types of events, and these can be configured on a per-endpoint basis by using event subscriptions.

Messages

For every event created in the account a copy will be sent in the form of a JSON message to every configured and enabled endpoint. An example of the JSON payload looks like:

{
  "events": [
    {
      "id": 1,
      "created_at": "2021-05-09T15:59:41.2800621Z",
      "resource_type": "test",
      "action": "created",
      "references": {
        "test_id": "Event Test"
      },
      "details": {
        "origin": "billingbooth",
        "cause": "test_created",
        "description": "The test event was generated."
      },
      "metadata": {}
    }
  ]
}

• An single webhook message may contain one or more events.
• Messages cannot be guaranteed to be sent in chronological order.
• The resource_type will identify the type of event, such as invoices, payments and so on.
• metadata will contain context-related information asuch as customer_reference, payment_provder and so on.

Events

Resource Type	Event	Description
test	test_created	Test webhook event sent from the portal
audit	audit_created	An audit entry was created
customers	customer_created	Customer has been created
	customer_updated	Existing customer details have been updated
	customer_activated	A previously suspended or cancelled customer has been re-activated
	customer_suspended	A previously active customer has been suspended
	customer_cancelled	A previously active customer has been cancelled
	customer_deleted	Existing customer has been deleted
credit_notes	credit_note_created	A new credit note has been created
	credit_note_deleted	An existing credit note has been deleted
invoices	invoice_created	A new invoice has been created
	invoice_updated	An existing invoice's status has been updated
	invoice_settled	An existing invoice has been settled
	invoice_deleted	An existing invoice has been deleted
ledger	ledger_entry_created	A new leger entry was added
	ledger_entry_deleted	An existing ledger entry was removed
mandates	mandate_created	A new payment mandate has been created
	mandate_updated	An existing payment mandate has been updated
	mandate_enabled	An existing payment mandate has been enabled
	mandate_disabled	An existing payment mandate has been disabled
	mandate_invalid	An existing payment mandate has been marked as invalid
	mandate_deleted	An existing payment mandate has been deleted
payments	payment_created	A new payment has been created
	*	A variety of events are fired off depending on the Payment Provider being used

Signature verification

Every message sent out has a request signature that can be used to verify the authenticity of the event.

To generate the signature each endpoint in Billingbooth has its own Secret key which can be obtained by going to Settings > Webhooks > Endpoints and clicking on the Reveal button next to the relevant endpoint. This key should be used to calculate the payload received from Billingbooth and should be kept secure.

To calculate the signature of a received event an Hash-based Messages Authentication Code (HMAC) should be used using an SHA256 hash function against the payload of the received event. Below is an example of how to calculate the signature in C#:

var payload = "{'message':'This is the payload'}";
var hmac = new HMACSHA256(Encoding.ASCII.GetBytes("Secret key"));
var signature = hmac.ComputeHash(Encoding.ASCII.GetBytes(payload)).Aggregate("", (s, e) => s + $"{e:x2}", s => s);

For every message sent out by Billingbooth, an HTTP header with the name of Webhook-Signature is included. The resulting signature variable in the code example above should be compared against the Webhook-Signature header of the request and if they match then the message is validated.

If validation matches, an HTTP 200 OK status should be returned, otherwise HTTP 498 Invalid Token should be returned. Any response statuses other than HTTP 200 are considered delivery failures in Billingbooth.