Applications can subscribe to Kill Bill events via HTTP.

Configuration

To do so, subscribe your handler (e.g. http://listener-app.acme:8080/callmeback) as such:

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"

Each event will then be POST’ed to that 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).

Events format

Each event is serialized as JSON 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

By design, events are generic and contain very limited information: it is expected that your handler calls back the Kill Bill APIs to retrieve the latest state of the objects before acting upon it.

In some cases however, specific events may contain further information, which are serialized as JSON in the metaData field (you can find metadata objects here).