Webhooks

---
name: webhooks
description: |
  Webhook subscriptions for the Ayrshare MCP server: register, unregister, and list HTTPS push notifications so an agent or app is notified on events instead of polling. Use whenever someone wants event push: "notify me when a post publishes", "let me know when a scheduled post goes out", "set up a webhook for new comments", "send mentions to my endpoint", "list our webhooks", "what webhooks are registered", "stop sending webhooks for comments", "unsubscribe from the messages webhook". Trigger when calling `mcp__ayrshare__register_webhook`, `mcp__ayrshare__unregister_webhook`, or `mcp__ayrshare__list_webhooks`, and even without "Ayrshare": if the user wants push notifications for social-post or social-account events through an assistant, this is the skill. To confirm a queued post actually published, prefer the `scheduled` webhook over polling (then optionally `get_post` / `get_post_history`).
---

# Ayrshare MCP — Webhooks

Three tools for subscribing your endpoint to Ayrshare events so you receive **push notifications instead of polling**:

- `mcp__ayrshare__register_webhook` — subscribe an HTTPS URL to one event action.
- `mcp__ayrshare__unregister_webhook` — cancel a subscription by action.
- `mcp__ayrshare__list_webhooks` — list current subscriptions.

All three are profile-scoped: choose the profile with the `profileKey` argument or the `Profile-Key` header (see Auth; the argument wins when both are set).

## Functions

| Tool | Purpose | Method + Endpoint | Required inputs | Optional inputs |
|------|---------|-------------------|-----------------|-----------------|
| `mcp__ayrshare__register_webhook` | Subscribe an HTTPS endpoint to a webhook action | `POST /hook` | `url` (**must be `https://`**), `action` (one webhook action) | `source` (string), `secret` (string — for signature verification) |
| `mcp__ayrshare__unregister_webhook` | Cancel a webhook subscription | `DELETE /hook` | `action` (one webhook action) | `source` |
| `mcp__ayrshare__list_webhooks` | List current webhook subscriptions | `GET /hook` | — | `allWebhooks` (bool), `source` |

**Webhook actions** (the `action` enum): `feed`, `social`, `scheduled`, `batch`, `messages`, `mentions`, `comments`, `automations`, `accountActivity`.

## Auth

All three tools are **profile-scoped**: choose the profile with an optional `profileKey` tool argument or the `Profile-Key` connection header (the argument wins when both are set). Pass `profileKey` on the call to manage one client profile's webhooks, or set the `Profile-Key` header (`.mcp.json` headers) to default the whole connection to it; with neither, calls manage the account's primary/Business profile. Beyond `profileKey`, these webhook tools take no `passthrough` object; their inputs are exactly the fields in the table above. Full model: `../getting-started/SKILL.md`.

## Usage guidance

- **`url` must be HTTPS.** `register_webhook` rejects non-`https://` URLs. The endpoint must be reachable so Ayrshare can deliver events to it.
- **Pick the right `action`.** One subscription = one action. The actions are `feed`, `social`, `scheduled`, `batch`, `messages`, `mentions`, `comments`, `automations`, `accountActivity`.
- **Confirming a queued post published — use `scheduled`, don't poll.** `scheduled` is the **platform-agnostic post-completion webhook**: it fires when a queued/scheduled post finishes processing. Register a `scheduled` webhook to be told when the post goes out, instead of repeatedly calling history. Once notified (or if you can't run an endpoint), you can confirm details with `mcp__ayrshare__get_post` (Ayrshare Post ID) or `mcp__ayrshare__get_post_history` — but the webhook is the push-based, no-polling path. See `../history/SKILL.md`.
- **Use `secret` to verify deliveries.** Pass a `secret` at registration so your endpoint can verify the signature on incoming payloads and reject spoofed calls.
- **`source` is a free-form tag** you can attach at register time and then filter on with `unregister_webhook` / `list_webhooks`. Use it to distinguish multiple subscriptions for the same action or different downstream consumers.
- **Unregister by `action`.** To stop notifications, call `unregister_webhook` with the same `action` (and `source` if you registered with one). To audit what's active, call `list_webhooks` (`allWebhooks: true` to widen the listing).

## Gotchas

- **Non-HTTPS URLs are rejected.** `register_webhook` requires `https://`. A plain `http://` or hostless URL fails.
- **One action per call.** `action` is a single value, not an array. To subscribe to multiple event types, register each separately.
- **`scheduled` is the post-completion signal, not `social`.** For "tell me when my queued post published," use `scheduled` (platform-agnostic, fires on post completion). Don't reach for polling loops when a `scheduled` webhook does it push-style.
- **Be deliberate about scope.** Which profile a webhook is registered/listed under is set by the `profileKey` argument (per call; it wins) or the connection's `Profile-Key` header; with neither it's the primary profile. Confirm you're targeting the intended profile before registering.
- **Unregister must match how you registered.** Cancel with the same `action` (and `source` if used). A mismatched `source` may leave a subscription active — verify with `list_webhooks`.
- **On failure, call `mcp__ayrshare__explain_error`, then surface it — don't loop.** `register_webhook`/`unregister_webhook` are writes: never auto-retry on a 4xx (bad URL, unknown action, wrong scope). Translate the error via `mcp__ayrshare__explain_error` and present it; 429 gets at most one retry. (Mirrors the global retry-safety rule.)