BeeBuzz

Webhooks

Webhooks let another service send trusted mode BeeBuzz notifications without running the CLI.

Use webhooks when the sender can call an HTTPS URL. Webhooks use trusted mode: BeeBuzz receives the notification content in plaintext and sends it via Web Push to the devices subscribed to the selected topics.

Create A Webhook

Open Account -> Webhooks and create a webhook.

Choose:

  • a name you will recognize later
  • one or more target topics
  • a priority, usually normal
  • a payload mode

Copy the webhook URL immediately after creation. The token in that URL is the webhook credential.

BeeBuzz Payload Mode

Use BeeBuzz mode when the sender can send a JSON body with title and body.

curl "$BEEBUZZ_WEBHOOK_URL" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Door opened",
    "body": "The front door opened at 18:42"
  }'

The webhook dispatches to the topics selected when you created it.

Custom Payload Mode

Use custom mode when the sender already has its own JSON shape.

For this payload:

{
	"event": {
		"summary": "Build failed",
		"details": "Deploy exited with code 1"
	}
}

Configure:

  • title path: event.summary
  • body path: event.details

BeeBuzz also supports simple array indexes in paths, for example events[0].summary.

Home Assistant Example

You can call a BeeBuzz webhook from Home Assistant with a rest_command.

rest_command:
  beebuzz_notify:
    url: 'https://hook.beebuzz.app/v1/webhooks/YOUR_WEBHOOK_TOKEN'
    method: post
    content_type: 'application/json'
    payload: >
      {
        "title": "{{ title }}",
        "body": "{{ body }}"
      }

Then call it from an automation:

action:
  - service: rest_command.beebuzz_notify
    data:
      title: 'Leak detected'
      body: 'The kitchen leak sensor is wet'

Create the webhook in BeeBuzz mode for this example.

Limits

  • Webhook request bodies are limited to 64 KB.
  • Webhooks use trusted mode, not end-to-end mode. BeeBuzz can read the plaintext payload before sending the notification via Web Push.
  • Webhook timestamps are generated by BeeBuzz when the notification is accepted.
  • A webhook token grants send access to the selected topics. Regenerate the token if it leaks.

Troubleshooting

If the webhook request succeeds but no notification arrives:

  1. confirm the receiving device is paired and subscribed to the webhook topics
  2. send a trusted-mode test from the Quickstart
  3. confirm the webhook token was copied from the same BeeBuzz account
  4. check that the custom title/body paths match the incoming JSON payload
  5. regenerate the webhook token if you are unsure where it has been stored