> For the complete documentation index, see [llms.txt](https://docs.mosip.io/1.2.0/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mosip.io/1.2.0/id-lifecycle-management/supporting-services/websub/websub-developer-guide.md).

# WebSub Developers Guide

## Overview

[WebSub](https://docs.mosip.io/1.2.0/modules/websub) module provides a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP webhooks.

Below is a list of tools required in WebSub:

1. Ballerina (Swan-Lake)
2. Any IDE (like Vs Code)
3. Kafka
4. Postman (any HTTP Client)
5. Git

### Software setup

1. Download [Ballerina](https://ballerina.io/downloads/) and install it as per instructions. (Use `bal -v` to ensure installation and version). ![](https://1836199994-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EyCrLbFom7vj7UcMIUZ%2Fuploads%2Fgit-blob-f1504546c98e8f6f861b9586c6fcbc7fdb332603%2Fwebsub-version-check.png?alt=media\&token=1b1d5061-35d8-4290-8ccf-2eb381540ff3)
2. Download [Kafka](https://kafka.apache.org/downloads) and install it.

### Source code setup

For the code setup, clone the repository and follow the guidelines mentioned in the [Code Contributions](https://docs.mosip.io/1.2.0/community/code-contributions).

### Importing and building

1. Open the hub and consolidator folders where `Ballerina.toml` is present.
2. Open the command prompt from the same folder.
3. Run the command `bal build` to build the hub and consolidator.
4. Open the project in VS Code either by `open with vs code` or from `File -> Open Folder`.

## Environment setup

1. Copy `websub-service.toml` and `websub-consolidator.toml` file from [mosip-config repository](https://github.com/mosip/mosip-config) to hub and consolidator folder respectively and rename both of them as `Config.toml`(case-sensitive). ![](https://1836199994-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EyCrLbFom7vj7UcMIUZ%2Fuploads%2Fgit-blob-8378bd67f571f2d0339f44b8f09654daf95a3722%2Fwebsub-config-file-placement.png?alt=media\&token=2c730860-637e-4781-b31c-d02e7294af33)
2. Run Configure and run Kafka, update `KAFKA_BOOTSTRAP_NODE` in `Config.toml` to point to your Kafka.

## Initialization and utilization of module

1. WebSub consists of consolidator and hub.
2. Consolidator should be started first, `Got to consolidator -> java -jar target/bin/<Jarname>`. (Config.toml should be in the same place where you are running this command).
3. Start WebSub with the same approach.
4. The APIs can be tried with the help of [kernel-websub-api](https://github.com/mosip/commons/tree/release-1.2.0/kernel/kernel-websubclient-api).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mosip.io/1.2.0/id-lifecycle-management/supporting-services/websub/websub-developer-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.