{"id":29305571,"url":"https://github.com/homebridge-plugins/homebridge-http-notification-server","last_synced_at":"2025-07-07T05:06:53.040Z","repository":{"id":32477013,"uuid":"134971411","full_name":"homebridge-plugins/homebridge-http-notification-server","owner":"homebridge-plugins","description":"An http/https server inside Homebridge to receive notifications from external programs","archived":false,"fork":false,"pushed_at":"2023-03-02T21:16:12.000Z","size":219,"stargazers_count":27,"open_issues_count":4,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-16T18:50:46.068Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/homebridge-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-26T15:08:47.000Z","updated_at":"2025-06-11T17:18:32.000Z","dependencies_parsed_at":"2024-09-25T16:40:36.305Z","dependency_job_id":null,"html_url":"https://github.com/homebridge-plugins/homebridge-http-notification-server","commit_stats":null,"previous_names":["bauer-andreas/homebridge-http-notification-server","homebridge-plugins/homebridge-http-notification-server"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/homebridge-plugins/homebridge-http-notification-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-notification-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-notification-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-notification-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-notification-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homebridge-plugins","download_url":"https://codeload.github.com/homebridge-plugins/homebridge-http-notification-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-notification-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262314909,"owners_count":23292465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-07T05:06:52.049Z","updated_at":"2025-07-07T05:06:53.016Z","avatar_url":"https://github.com/homebridge-plugins.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# homebridge-http-notification-server\n\n`homebridge-http-notification-server` can be used together with [Homebridge](https://github.com/homebridge/homebridge) \nhttp accessories. Http accessories are Homebridge plugins, which forward HomeKit requests to another program over a \nhttp request. An example for such an accessory would be my \n[homebridge-http-switch](https://github.com/Supereg/homebridge-http-switch).\n\nThe problem with such accessories is when \nthe state of the external program changes it cannot be directly reflected in HomeKit. So one solution would be that \nevery http accessory packs its own http server to receive state changes. But with multiple switches this becomes a mess \nvery fast.\n\nThis is where the `homebridge-http-notification-server` comes in. It is basically a Homebridge plugin, which is loaded by \nHomebridge like any other plugin but doesn't register any accessories or platforms. Instead it starts ONE http or https \nserver. Http accessories can register with an unique id. Any request the external program will send to the notification \nserver will be forwarded to the accessory which specified the respective `notificationID`.\n\n## Installation\n\n`sudo npm install -g homebridge-http-notification-server`\n\n## Configuration\n\nThe configuration file is located in the homebridge directory and needs to be called `notification-server.json`\n\nExample:\n```json\n{\n    \"hostname\": \"127.0.0.1\",\n    \"port\": 8080,\n\n    \"ssl\": {\n        \"privateKey\": \"/path/to/private-key.prm\",\n        \"certificate\": \"/path/to/certificate.cert\"\n    }\n}\n```\n\n* `hostname` is optional, default value is `0.0.0.0`\n* `port` is required, default value is `8080`\n* `ssl` is optional. When specified notification-server will create an https server with the specified `privateKey` and \n`certificate`. Otherwise a default unsecured http server is started.\n\n## How to implement 'homebridge-http-notification-server' into your project\n\n### Implementation in the homebridge accessory (receiver)\n\nFirst of all you need to specify a handler function in your homebridge accessory. `homebridge-http-notification-server` \nlocates its registration function in the `global` variable `notificationRegistration` at plugin initialization time.\n\nIn order to be sure, that `homebridge-http-notification-server` was already loaded by homebridge, you listen on the event \n`didFinishLaunching` of the homebridge api.\n\n`notificationRegistration(notificationId, handlerFunction[, password])`\nnotificationRegistration function has three parameters, the first two are required.\n* `notificationId`: this is id needs to be unique per homebridge instance. It is later used to identify the accessory when \na request is made to the notification-server\n* `handlerFunction`: function which is called when the notification-server received a request for the specified `notificationId`.\nIt needs to have one parameter, which is the json body from the http request.\n* `password`: this parameter is fully optional. If specified every request to the notification-server must be authenticated \nwith the specified password. Later more on how a request is constructed.\n\n\nExample http accessory:\n```javascript\nlet api;\n\nmodule.exports = function (homebridgeAPI) {\n    api = homebridgeAPI;\n\n    homebridgeAPI.registerAccessory(\"homebridge-http-example-accessory\", \"HTTP-ACCESSORY\", HTTP_ACCESSORY);\n};\n\nfunction HTTP_ACCESSORY(log, config) {\n    // Some initialization\n    this.name = config.name;\n    \n    this.service = new Service.Switch(this.name);\n    this.service.getCharacteristic(Characteristic.On)\n            .on(\"get\", this.getStatus.bind(this))\n            .on(\"set\", this.setStatus.bind(this));\n\n    api.on('didFinishLaunching', function() {\n        // check if notificationRegistration is set, if not 'notificationRegistration' is probably not installed on the system\n        if (global.notificationRegistration \u0026\u0026 typeof global.notificationRegistration === \"function\") {\n            try {\n                global.notificationRegistration(\"accessory-identifier\", this.handleNotification.bind(this), \"top-secret-password\");\n            } catch (error) {\n                // notificationID is already taken\n            }\n        }\n    }.bind(this));\n}\n\nHTTP_ACCESSORY.prototype = {\n    \n    identify: function (callback) {\n        this.log(\"Identify requested!\");\n        callback();\n    },\n\n    getServices: function () {\n        return [this.service];\n    },\n    \n    handleNotification: function (jsonRequest) {\n        const service = jsonRequest.service; // value is optional and only relevant if your accessory exposes multiple services\n        \n        const characteristic = jsonRequest.characteristic;\n        const value = jsonRequest.value;\n        \n        // #testCharacteristic returns true if the service was added the specified characteristic.\n        //  you could ad additional checks to adjust for your needs\n        const validCharacteristic = this.service.testCharacteristic(characteristic);\n        \n        if (!validCharacteristic) {\n            this.log(\"Encountered unknown characteristic when handling notification: \" + characteristic);\n            return; // in this example we ignore invalid requests\n        }\n        \n        this.service.updateCharacteristic(characteristic, value);\n    },\n    \n    getStatus: function(callback) {\n        // request\n    },\n    \n    setStatus: function(on, callback) {\n        // request\n    }\n    \n};\n```\n\n### Implementation in the http application (sender)\n\nThe http application sends a request to the notification-server (inside of homebridge) to update a value of a HomeKit \ncharacteristic. The http request must be a `POST` request. The url would be constructed as follows:\n\n`http://\u003chostname\u003e:\u003cport\u003e/\u003cnotificationID\u003e` (`https://...` if ssl is turned on)\n\nIn our example the url would look like the following:\n`http://127.0.0.1:8080/accessory-identifier`\n\nThe POST body would look like the following:\n```json5\n{\n    \"characteristic\": \"On\",\n    \"value\": true,\n    \"password\": \"your-top-secret-password\",\n    \n    \"accessory\": \"example-accessory\", // optional, plugin defined \n    \"service\": \"switch-service\", // optional, plugin defined\n}\n```\n**Common properties**: \n* `characteristic` is required. It represents the name of the characteristic which is going to be updated. Value must be \na string. Of course this only works with characteristics which have the `notify` permissions in the HAP specifications. \n* `value` is required. \n* `password` optional, but required if your accessory defined a password\n\n**Plugin defined properties**:\n* `accessory` is fully optional. The type and usage is up to be defined by the plugin. This project just suggest\n    this property to be used to identify a given accessory, if your plugin exposes multiple accessories.\n* `service` is fully optional. The type and usage is up to be defined by the plugin. This project just suggest\n    this property to be used to identify a given service, if your plugin exposes multiple services.\n\n## Some compatible http accessories\n\n* [homebridge-http-switch](https://github.com/Supereg/homebridge-http-switch)\n* [homebridge-http-lightbulb](https://github.com/Supereg/homebridge-http-lightbulb)\n* [homebridge-http-outlet](https://github.com/Supereg/homebridge-http-outlet)\n* [homebridge-http-humidity-sensor](https://github.com/Supereg/homebridge-http-humidity-sensor)\n* [homebridge-http-temperature-sensor](https://github.com/Supereg/homebridge-http-temperature-sensor)\n\n- [homebridge-http-rgb-push](https://github.com/QuickSander/homebridge-http-rgb-push) by Sander van Woensel\n- [homebridge-http-ambient-light-sensor](https://github.com/QuickSander/homebridge-http-ambient-light-sensor) by Sander van Woensel\n- [homebridge-http-moisture-sensor](https://github.com/Pythonaire/homebridge-http-moisture-sensor) by Phytonaire\n\n_Notify me if you want to see your project here._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-notification-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-notification-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-notification-server/lists"}