Webhooks

Use webhooks when an external service can send JSON to an HTTPS URL but cannot use the BeeBuzz CLI.

Webhooks use trusted delivery. BeeBuzz receives the notification content in plaintext before sending it to your devices.

Create A Webhook

Open Account -> Webhooks and create a webhook.

Choose:

• a name
• one or more target topics
• a priority
• a payload mode

Copy the webhook URL when BeeBuzz shows it. The token in the URL is the webhook credential.

BeeBuzz Payload Mode

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

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

Custom Payload Mode

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

Example payload:

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

Configure:

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

Simple array indexes are supported, for example events[0].summary.

Inspect Payload

If you do not know the correct title and body paths, use the inspect workflow in the web app.

BeeBuzz creates a temporary inspect URL. Send one test payload to that URL, then choose the fields that should become the notification title and body.

Inspect mode captures the payload for setup. It does not send a notification.

Token Handling

A webhook token can send to the topics selected for that webhook.

Regenerate the token if it leaks or if you are unsure where it has been stored.

Limits

• webhook request bodies are limited to 64 KiB
• priority can be normal or high
• webhooks use trusted delivery, not end-to-end encryption

Common Issues

If the webhook request succeeds but no notification arrives:

• confirm the receiving device is paired
• confirm the device is subscribed to the webhook topics
• confirm the custom title and body paths match the incoming JSON
• regenerate the webhook token if the stored URL may be wrong