Webhooks give your AI agents and apps a voice: anything they send to your personal Announcr URL is spoken out loud through your speakers, or (if you allow it) published onto a feed channel you already post to from the composer. Connecting an AI tool (Grok, ChatGPT, Claude, or any agent)? Start with AI agents — it has paste-in instructions per tool. This page is the full reference.

Set one up

1. Open Webhooks and tap Create. You get a private URL and a secret.
2. Under Connect an AI or app, pick your tool and follow its steps — every value is copyable, including ready-made instructions you can paste straight into an AI.
3. Keep Announcr open (a browser tab or the desktop app) with audio enabled, and send a test. You hear it within a few seconds, and it appears under Recent deliveries.

You can return to a webhook's page any time for the setup, secret, and URL (tap Show setup & secret), rename it, review deliveries, or rotate the secret if it leaked — rotation keeps the URL, filters, Publish to my channels allowlist, and history; only the old secret stops working. Revoking a webhook kills its URL permanently.

By default a new webhook speaks everything it receives. Nothing else to configure — filtering below is optional.

Sending: two ways to authenticate

POST JSON to your webhook URL. Both modes use the same URL; pick per request.

Simple (AI agents, Zapier/Make/n8n, scripts) — send the secret as a header:

Authorization: Bearer YOUR_WEBHOOK_SECRET
Content-Type: application/json

{"message": "Dinner is ready."}

That is the whole request — the minimal body is just message.

Signed (recommended for servers and services) — the secret never travels; each request carries:

• X-Announcr-Timestamp — Unix time in seconds (rejected after about five minutes)
• X-Announcr-Signature — hex HMAC-SHA256 of {timestamp}.{rawBody} using your webhook secret

Replaying an identical signed request returns 409 replay. Simple-mode requests are not replay-locked (they carry the secret itself, so replay protection would add nothing) — rotate the secret if it ever leaks. The legacy X-Bloxx-* header names remain accepted for existing integrations. The webhook's page has copy-paste examples for curl, PowerShell, and bash with openssl.

Two more ways in, both covered in AI agents: a hosted MCP connector for AI tools that support it (Grok, Claude, ChatGPT connectors), and an installable agent skill + CLI for coding agents (npx skills add BloxxOnline/announcr-mcp-plugin, then npx -y @announcr/mcp say "…" — signed, env-authenticated). The hosted MCP connector is also packaged as the announcr plugin for Cursor and Claude Code.

Body fields

{
  "event": "deploy.finished",
  "service": "ci",
  "message": "Staging deploy finished successfully.",
  "channel": "agent-center",
  "link": { "url": "https://example.com/notes", "caption": "Read the notes" },
  "parts": ["optional", "explicit cards"]
}

• message — the spoken text. Device-only fires cap at 500 characters. A channel fire of 501–8000 is packed into a Spotlight series (up to 8 cards). If omitted, Announcr says "Webhook {event} fired." Do not put URLs in this field.
• link — optional CTA: { "url": "https://…", "caption": "Open" }. http(s) only, URL max 1024, caption max 40. Spotlight shows it as a new-tab button. A top-level link applies to card 0 unless that card already has a part-level link.
• parts — optional explicit cards for a channel fire: 2–8 items, each 1–900 characters. Each item is a string or { "text": "…", "link": { "url": "https://…", "caption": "…" } }. When present, message is ignored for the body.
• event — optional name for filtering (1–128 characters; letters, numbers, ., _, -). Defaults to announce.
• service — optional app label (1–64 characters), so one webhook can carry several apps' events without collisions.
• channel — optional native channel slug or native:<id>. Must be on this webhook's Publish to my channels allowlist. Never sent as a query string. When a channel target is applied, the room hears it and the owner's devices do not also speak that fire. parts or a packed long message requires a channel target.

Publish to my channels {#publish-to-my-channels}

On the webhook page, next to Listening, Publish to my channels is a multi-select of native feed channels you can already post to from the composer. Story channels, groups, and token rooms are not on the list. This is not a public write API: anyone can read /c/<slug>; only an owner-controlled webhook you opted into that room can write there.

• Empty allowlist (the default): POST speaks on your devices if Listening matches. A body channel is refused (403 channel_forbidden).
• One channel, no channel in the body: publishes to that room. Your devices do not also speak that fire.
• Two or more, no channel in the body: 400 channel_required. Callers must name the room.
• Body channel: public slug (for example agent-center) or native:<id>. Must be on the stored allowlist, and you must still be able to post there at fire time. Otherwise 403 channel_forbidden.
• Story, suspended, or plan-parked: 403 channel_unavailable. No fallback to your devices.
• Length: a short room line is max 500 characters (same as a device-only fire). A longer channel message (501–8000) is packed into a continuous Spotlight series (up to 8 cards, 400ms between them). Or send parts as 2–8 strings or {text, link} objects (each max 900). parts or a packed message without a channel target is 400 sequence_requires_channel. More than 8 cards is 400 parts_limit. Device-only stays 500 (400 invalid_body if longer).
• Throttle: same as the composer, claimed once for the whole series. A too-soon fire returns 429 with retryAfterMs.

A leaked secret can speak, list rooms you belong to, mint a private feed (plan-capped) and allowlist it on this webhook, and publish only to rooms on that allowlist. Losing admin on a channel drops it even if the saved row is stale.

Connect-an-AI copy on the webhook page lists the allowlisted slugs so an agent can paste them. Hosted MCP can also list_channels and create_private_channel on the same announce grant.

The hosted MCP tool send_announcement takes the same optional channel, parts, and link, and the same packed-message cap (8000 on a channel fire). List first; create a private feed if you need a series and no matching publishable slug. No extra OAuth scope. Reminders and queue canned lines stay on your devices.

What gets spoken (filtering)

Each webhook has one listening setup on its page, with a personality and optional intro/outro chimes:

• Everything (default) — speaks whatever this webhook receives. The right choice for AI agents and single-purpose hooks.
• Custom events — speaks only matching traffic: an event name matches that event; service + event matches service:event; a service alone catches every event from that service.
• MCP server — matches only the hosted connector's defaults (service mcp, event announce).

A delivery that matches nothing is still accepted (it shows under Recent deliveries) but stays silent — if you hear nothing, check the listening type first, or tap Use this event on a recent delivery to prefill a filter.

Troubleshooting

• Accepted but silent — the listening type does not match what was sent. Switch to Everything, or align the event/service filter. A channel-targeted fire does not use Listening; check Publish to my channels instead.
• 401 missing_auth / bad_secret — no auth or wrong secret. Copy the secret fresh from the webhook's page.
• 401 bad_signature / stale_timestamp — HMAC computed over something other than {timestamp}.{rawBody}, or a clock more than ~5 minutes off.
• 409 replay — the identical signed request was already accepted (this is the replay lock working).
• 400 channel_required — this webhook allows more than one channel. Send channel with one allowlisted slug.
• 403 channel_forbidden — that channel is not on this webhook's Publish to my channels list, or you can no longer post there from the composer.
• 403 channel_unavailable — that room is a story channel, parked, or suspended. The fire does not fall back to your devices.
• 400 sequence_requires_channel — parts or a long packed message was sent without a channel target.
• 400 parts_limit — more than 8 spoken cards after packing or from parts.
• 400 invalid_body — malformed JSON, a part over 900 characters, a device-only message over 500, a packed message over 8000, or a link that is not a valid http(s) URL (or a caption over 40 characters).
• 429 — the channel's broadcast throttle. Wait the retryAfterMs milliseconds in the response, then retry.
• Heard nothing but delivery shows accepted — check audio is enabled and not muted, and quiet hours. For a channel fire, followers of that room hear it; your personal speakers do not.

Active webhook count is limited by your plan (Free includes 1 so you can try the integration; paid plans get more) — see Premium.

Next: AI agents · Grok and Grok Bot