KillBill :: Webhook Server 🔔🔎

Kill Bill generates various events when certain actions occur within the system. This server is designed to handle these events by utilizing the push notifications feature, allowing it to subscribe to and process such events via HTTP.

The Webhook Server provides a robust and flexible way to manage and respond to Kill Bill events, ensuring seamless integration with your existing infrastructure.

🚀 This project is also available on :

 
  see Flask version 
 

🔧 Features

• ✅ Single-tenant support
• ❌ Multi-tenant support (🚧upcoming...)
• ✅ RESTful API endpoints
• ✅ Config killbill notification subscription
• ❌ Swagger documentation
• ❌ Authentication system
• ✅ Logger events
• ✅ Event handling functions
• ❌ Database support
• ➖ Killbill models support (included in killbill service)

🌳 File Structure

├───src/
│   ├───middleware/     # Middleware functions for request/response processing
│   ├───models/         # Models objects for request/response processing
│   │
│   ├───services/       # Vendor logic and service layer
│   │   └───killbill.js
│   ├───helpers/        # Utility functions and helper methods
│   │   └───...
│   │
│   ├───routes/         # Route definitions and handlers
│   │   └───config.js
│   │   └───listener.js
│   │
│   ├───actions/        # Business logic and actions performed for each event
│   ├───events/         # Event handlers and listeners
│   │   └───mapping.js
│   │   └─── ...
│   │
│   ├───logger.js       # Logging configuration and utility functions
│   └───index.js        # Main application entry point
│
│
├───test/               # Test functions here
├───Dockerfile          # Instructions for building the Docker image
├───.env                # Environment variables for the **application**
├───app.log             # logs for the **application**
└───package.json

• src > actions/ : Directory containing actions such as payment processing, email notifications, and mobile app notifications. These actions handle specific tasks and business logic related to user interactions and system events.

• src > index.js : The main entry point of the application. It sets up the Express server, initializes middleware and routes.

• src > logger.js : Sets up the logger to save logs to a file, including the format and logging level.

• src > helpers > killbill.js : Helper functions and utilities specific to interacting with the Kill Bill API.

📍 Endpoints

PROCESS events from Killbill's server.

⚠️ This is a webhook endpoint. Do not use it !! ( Just killbill automatic flow are authorized.)

# fn() src/routes/listener/POST
curl -X POST {HOST}/kb/listener/ \
     -H 'Content-Type: application/json' \
     -d '{
        eventType : "{EVENT_TYPE}"
        ...any
        }'

Config Killbill callback notifications.

REFRESH notifications subscription to Killbill.

# fn() src/routes/config/POST
curl -X POST {HOST}/kb/config/ \
     -H 'Content-Type: application/json' \
     -d '{
        "cb": "The callback URL for Killbill notifications. If not provided, the default URL will be used."
        }'

GET notifications subscription to Killbill.

# fn() src/routes/config/GET
curl -X GET {HOST}/kb/config/ \
     -H 'Content-Type: application/json'

DELETE notifications subscription to Killbill.

# fn() src/routes/config/DELETE
curl -X DELETE {HOST}/kb/config/ \
     -H 'Content-Type: application/json' \

NOTE : for more info please read the docstring inside each route function.

🔔 Events types Handlers

This is a handlers about each event type from killbill's server.

EVENT NAME	LOCATION	KB Generation Condition
ACCOUNT_CREATION	src > events > account_creation > handle_account_creation	A new customer account is created
ACCOUNT_CHANGE	src > events > account_change > handle_account_change	A customer account is modified
BLOCKING_STATE	src > events > blocking_state > handle_blocking_state	There is a change in the state of an entitlement or billing
BROADCAST_SERVICE	src > events > broadcast_service > handle_broadcast_service	Used to broadcast an event to other Kill Bill nodes (Typically used for plugin related events like plugin installation, plugin uninstallation, plugin start, plugin stop, etc.)
SUBSCRIPTION_CREATION	src > events > subscription_creation > handle_subscription_creation	A new subscription is created
SUBSCRIPTION_PHASE	src > events > subscription_phase > handle_subscription_phase	A subscription transitions into a different phase
SUBSCRIPTION_CHANGE	src > events > subscription_change > handle_subscription_change	A subscription is modified
SUBSCRIPTION_CANCEL	src > events > subscription_cancel > handle_subscription_cancel	A subscription is cancelled
SUBSCRIPTION_UNCANCEL	src > events > subscription_uncancel > handle_subscription_uncancel	A subscription cancellation is undone (Note that subscription cancellation cannot be undone once the cancellation becomes effective)
SUBSCRIPTION_BCD_CHANGE	src > events > subscription_bcd_change > handle_subscription_bcd_change	The subscription BCD is changed
ENTITLEMENT_CREATION	src > events > entitlement_creation > handle_entitlement_creation	A new entitlement is created
ENTITLEMENT_CANCEL	src > events > entitlement_cancel > handle_entitlement_cancel	An entitlement is cancelled
BUNDLE_PAUSE	src > events > bundle_pause > handle_bundle_pause	A subscription bundle is paused
BUNDLE_RESUME	src > events > bundle_resume > handle_bundle_resume	A subscription bundle is resumed
OVERDUE_CHANGE	src > events > overdue_change > handle_overdue_change	There is a change is an overdue state
INVOICE_CREATION	src > events > invoice_creation > handle_invoice_creation	A new invoice is generated
INVOICE_ADJUSTMENT	src > events > invoice_adjustment > handle_invoice_adjustment	An invoice is adjusted
INVOICE_NOTIFICATION	src > events > invoice_notification > handle_invoice_notification	An invoice is going to be generated for an account in the future (Can be used to notify customers about upcoming bills)
INVOICE_PAYMENT_SUCCESS	src > events > invoice_payment_success > handle_invoice_payment_success	An invoice payment is successful
INVOICE_PAYMENT_FAILED	src > events > invoice_payment_failed > handle_invoice_payment_failed	An invoice payment fails
PAYMENT_SUCCESS	src > events > payment_success > handle_payment_success	Payment is successful
PAYMENT_FAILED	src > events > payment_failed > handle_payment_failed	Payment fails
TAG_CREATION	src > events > tag_creation > handle_tag_creation	A new tag is associated with a Kill Bill resource (account, invoice, etc.)
TAG_DELETION	src > events > tag_deletion > handle_tag_deletion	A tag associated with a Kill Bill resource (account, invoice, etc.) is deleted
CUSTOM_FIELD_CREATION	src > events > custom_field_creation > handle_custom_field_creation	A custom field is created
CUSTOM_FIELD_DELETION	src > events > custom_field_deletion > handle_custom_field_deletion	A custom field is deleted
TENANT_CONFIG_CHANGE	src > events > tenant_config_change > handle_tenant_config_change	A Tenant configuration is modified (So, any changes to a catalog, overdue config, etc. within a tenant triggers this event)
TENANT_CONFIG_DELETION	src > events > tenant_config_deletion > handle_tenant_config_deletion	A Tenant configuration is deleted

NOTES :

• for more info please read the docstring inside each handler function.
• to know more about event handler mapping read the comments bellow the src/routes/listener/POST route function.

🚀 Get started

Clone the Repository and go to the project directory:

git clone https://github.com/albertolicea00/killbill-webhook-node-server.git
cd killbill-webhook-node-server

Environment Variables

To run this project, you will need to add the .env.example environment variables to your .env file

Create and activate virtual environment (optional)

jsthon -m venv venv

• Mac / Linux : source venv/bin/activate

• Windows : venv\Scripts\activate

• Windows ( bash ) : source venv/Scripts/activate

Install dependencies

npm install

Run server

# development mode
npm run dev

# production mode
npm run start

Run lint

npm run format

Run tests

npm run test

Feel free to use with docker

# Build the image
docker build -t killbill-webhook-server .

# Create container
docker run --name killbill-webhook-container -d -p 5000:5000 killbill-webhook-server

# Run container
docker run killbill-webhook-container

# Stop container
docker stop killbill-webhook-server

# Remove container
docker rmi killbill-webhook-container

📦 Tech Stack

• express

• axios

• killbill

• dotenv

• nodemon

• prettier

• winston