Skip to content
Blipbar docs

Webhooks

The host listens on 127.0.0.1:<port>, with the port in webhook.json (47811 by default, falling back if taken). Every request needs the header Authorization: Bearer <token>. Browsers can’t send that header cross-origin without a preflight, and the server never answers preflights, so web pages can’t reach it.

Route Body Effect
GET /v1/health none {ok: true, version}
POST /v1/blips a payload, or an array of payloads Pushed straight into the store as source webhook. An id without a / gets the webhook/ prefix (a missing one is made from the title: webhook/hello-blipbar), and a missing seq is stamped. All or nothing: one bad payload is a 400 naming it and its field ({"error": "invalid payload at [1]: \"data.value.amount\" should be a number"}).
POST /v1/blips/<id>/end {state?, dismissAfter?} ends the blip
DELETE /v1/blips/<id> none removes the blip
POST /v1/hooks/<extension-id> any JSON → extension.event {type: "webhook"}. With ?await=<seconds> (at most 600), the response is held until the extension calls ctx.respond(...) or the wait runs out (then 204). This is how “approve from the notch” works for agent permission hooks.

webhook.json lives in ~/Library/Application Support/Blipbar/. Blipbar writes a new token each time it launches, so read the file on every run instead of copying the token.

A pushed blip needs a title, a layout and that layout’s data, the same shapes the SDK’s builders make. v, emittedAt and seq are filled in when they’re left out. Post the same id again to update it. The end and DELETE routes take the id either way (backup or webhook/backup). While the notch is open, a pushed blip shows at the end of the panel.

Terminal window
config=~/Library/Application\ Support/Blipbar/webhook.json
port=$(plutil -extract port raw -o - "$config")
token=$(plutil -extract token raw -o - "$config")


# Show a backup running, 40% through. Post again with the same id to move it on.
curl -s "http://127.0.0.1:$port/v1/blips" \
  -H "Authorization: Bearer $token" -H "Content-Type: application/json" \
  -d '{"id": "backup", "title": "Backup", "icon": "externaldrive.fill", "state": "running",
       "layout": "progress", "data": {"fraction": 0.4, "step": "Copying Photos"}}'


# When it's done.
curl -s -X POST "http://127.0.0.1:$port/v1/blips/webhook/backup/end" \
  -H "Authorization: Bearer $token" -H "Content-Type: application/json" \
  -d '{"state": "success"}'