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 \
-u admin:password \
-H 'X-Killbill-CreatedBy: admin' \
-H "Content-Type: application/json" \
"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 theExtBusEventType
enum)objectType
: type of object being updated (as defined by the ObjectType enum)accountId
: account id being updatedobjectId
: object id being updatedmetaData
: 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).