Notifiers

Manage webhook / notification channels (create, update, delete, and send test pings).

NotifiersClient

Sub-client for notification-channel (notifier) endpoints.

Accessed via HomeboxClient.notifiers.

Source code in homebox/client.py

class NotifiersClient:
    """Sub-client for notification-channel (notifier) endpoints.

    Accessed via ``HomeboxClient.notifiers``.
    """

    def __init__(self, client: HomeboxClient):
        """Initialise the notifiers sub-client with the shared root client."""
        self.client = client

    def get_notifiers(self) -> list[NotifierOut]:
        """Return all notification channels configured for the current user.

        Returns:
            list[NotifierOut]: Each notifier includes its ID, name, webhook URL,
                active flag, and group/user association.
        """
        data = self.client._request("get", "/v1/notifiers")
        return [NotifierOut(**item) for item in data.get("data", [])]

    def create_notifier(self, data: NotifierCreate) -> NotifierOut:
        """Create a new notification channel.

        Args:
            data: Notifier creation payload.  ``name`` and ``url`` (webhook) are
                required; ``isActive`` defaults to server-side behaviour when
                omitted.

        Returns:
            NotifierOut: Representation of the newly created notifier.
        """
        return NotifierOut(**self.client._request("post", "/v1/notifiers", data=data.model_dump()))

    def test_notifier(self, url: str):
        """Send a test notification to the given webhook URL.

        Args:
            url: Webhook URL to test (does not need to match an existing
                notifier).
        """
        params = {"url": url}
        self.client._request("post", "/v1/notifiers/test", params=params)

    def update_notifier(self, id: str, data: NotifierUpdate) -> NotifierOut:
        """Replace a notifier's settings with the provided data.

        Args:
            id: UUID of the notifier to update.
            data: Updated notifier payload.  ``name`` is required; ``url`` and
                ``isActive`` are optional.

        Returns:
            NotifierOut: Updated notifier representation.
        """
        return NotifierOut(**self.client._request("put", f"/v1/notifiers/{id}", data=data.model_dump()))

    def delete_notifier(self, id: str):
        """Permanently delete a notification channel.

        Args:
            id: UUID of the notifier to delete.
        """
        self.client._request("delete", f"/v1/notifiers/{id}")

__init__

__init__(client: HomeboxClient)

Initialise the notifiers sub-client with the shared root client.

Source code in homebox/client.py

def __init__(self, client: HomeboxClient):
    """Initialise the notifiers sub-client with the shared root client."""
    self.client = client

get_notifiers

get_notifiers() -> list[NotifierOut]

Return all notification channels configured for the current user.

Returns:

Type	Description
list[NotifierOut]	list[NotifierOut]: Each notifier includes its ID, name, webhook URL, active flag, and group/user association.

Source code in homebox/client.py

def get_notifiers(self) -> list[NotifierOut]:
    """Return all notification channels configured for the current user.

    Returns:
        list[NotifierOut]: Each notifier includes its ID, name, webhook URL,
            active flag, and group/user association.
    """
    data = self.client._request("get", "/v1/notifiers")
    return [NotifierOut(**item) for item in data.get("data", [])]

create_notifier

create_notifier(data: NotifierCreate) -> NotifierOut

Create a new notification channel.

Parameters:

Name	Type	Description	Default
data	NotifierCreate	Notifier creation payload. name and url (webhook) are required; isActive defaults to server-side behaviour when omitted.	required

Returns:

Name	Type	Description
NotifierOut	NotifierOut	Representation of the newly created notifier.

Source code in homebox/client.py

def create_notifier(self, data: NotifierCreate) -> NotifierOut:
    """Create a new notification channel.

    Args:
        data: Notifier creation payload.  ``name`` and ``url`` (webhook) are
            required; ``isActive`` defaults to server-side behaviour when
            omitted.

    Returns:
        NotifierOut: Representation of the newly created notifier.
    """
    return NotifierOut(**self.client._request("post", "/v1/notifiers", data=data.model_dump()))

test_notifier

test_notifier(url: str)

Send a test notification to the given webhook URL.

Parameters:

Name	Type	Description	Default
url	str	Webhook URL to test (does not need to match an existing notifier).	required

Source code in homebox/client.py

def test_notifier(self, url: str):
    """Send a test notification to the given webhook URL.

    Args:
        url: Webhook URL to test (does not need to match an existing
            notifier).
    """
    params = {"url": url}
    self.client._request("post", "/v1/notifiers/test", params=params)

update_notifier

update_notifier(id: str, data: NotifierUpdate) -> NotifierOut

Replace a notifier's settings with the provided data.

Parameters:

Name	Type	Description	Default
id	str	UUID of the notifier to update.	required
data	NotifierUpdate	Updated notifier payload. name is required; url and isActive are optional.	required

Returns:

Name	Type	Description
NotifierOut	NotifierOut	Updated notifier representation.

Source code in homebox/client.py

def update_notifier(self, id: str, data: NotifierUpdate) -> NotifierOut:
    """Replace a notifier's settings with the provided data.

    Args:
        id: UUID of the notifier to update.
        data: Updated notifier payload.  ``name`` is required; ``url`` and
            ``isActive`` are optional.

    Returns:
        NotifierOut: Updated notifier representation.
    """
    return NotifierOut(**self.client._request("put", f"/v1/notifiers/{id}", data=data.model_dump()))

delete_notifier

delete_notifier(id: str)

Permanently delete a notification channel.

Parameters:

Name	Type	Description	Default
id	str	UUID of the notifier to delete.	required

Source code in homebox/client.py

def delete_notifier(self, id: str):
    """Permanently delete a notification channel.

    Args:
        id: UUID of the notifier to delete.
    """
    self.client._request("delete", f"/v1/notifiers/{id}")