Applications can subscribe to Kill Bill events via HTTP. This feature is known as push notifications. This document provides information about the push notifications feature.

Overview

Push notifications are a convenient way to get notified about events from the system. One can register a callback, i.e, a valid URL that will be called whenever there is an event dispatched for a tenant.

The slate documentation provides an overview of the API methods related to push notifications. This document provides further details.

Configuration

To configure a push notification, you need to register a handler (e.g. http://listener-app.acme:8080/callmeback). You can use the Register a Push Notification API method as follows:

curl -v \
     -X POST \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -H "X-Killbill-Reason: demo" \
     -H "X-Killbill-Comment: demo" \
     "http://127.0.0.1:8081/1.0/kb/tenants/registerNotificationCallback?cb=http://listener-app.acme:8080/callmeback"

This registers http://listener-app.acme:8080/callmeback as the callback URL for this tenant. Each event will then be POST’ed to this url.

If a non-2xx response code is returned, notifications will be retried at a later time as configured by the per-tenant configuration parameter org.killbill.billing.server.notifications.retries (e.g. 15m,30m,2h,12h,1d).

Other Operations

Kill Bill provides some more API endpoints related to push notifications as follows:

Events format

As explained earlier, once a handler is registered, each event is POST’ed to that url. An event is an object of the type ExtBusEvent. Each event object is serialized as a JSON string and contains the following fields:

  • eventType: type of event (as defined by the ExtBusEventType enum)

  • objectType: type of object being updated (as defined by the ObjectType enum)

  • accountId: account id being updated

  • objectId: object id being updated

  • metaData: event-specific metadata, serialize as JSON.

You can also read the Kill Bill Events document to know more about events

Further Information