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:
Retrieve a registered push notification endpoint - Can be used to retrieve a registered push notification handler.
Delete registered push notification endpoint - Can be used to delete a registered push notification handler.
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 updatedobjectId
: object id being updatedmetaData
: event-specific metadata, serialize as JSON.
You can also read the Kill Bill Events document to know more about events