Update to Speak AI

{
  "description": "Receive Speak AI events on your own server with outbound webhooks, and explain where automations live. Use this when the user wants Speak to notify their system when a recording is created, processed or updated, wants to register, list, update or delete a webhook, needs to handle webhook deliveries reliably, or asks to build or run an automation. Covers create_webhook, list_webhooks, update_webhook and delete_webhook, the delivery body and idempotent handling with deliveryId, and points automation requests to the Speak AI web app. Keywords include webhook, outbound webhook, callback URL, event delivery, retry, idempotency, automation, workflow, trigger.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 291
    }
  ],
  "name": "automations-and-webhooks",
  "skill_md_contents": "---\nname: automations-and-webhooks\ndescription: Receive Speak AI events on your own server with outbound webhooks, and explain where automations live. Use this when the user wants Speak to notify their system when a recording is created, processed or updated, wants to register, list, update or delete a webhook, needs to handle webhook deliveries reliably, or asks to build or run an automation. Covers create_webhook, list_webhooks, update_webhook and delete_webhook, the delivery body and idempotent handling with deliveryId, and points automation requests to the Speak AI web app. Keywords include webhook, outbound webhook, callback URL, event delivery, retry, idempotency, automation, workflow, trigger.\nmetadata:\n  server-version: \"1.41.1\"\n  categories: \"webhooks\"\n  tool_count: \"4\"\n---\n# Automations and webhooks\n\nThe user's explicit instructions take priority over this skill. When they ask for something different from the steps below, do what they asked, and confirm with them before any action that deletes, overwrites, or sends data outside Speak AI.\n\nThis skill covers outbound webhooks, which send Speak events to a URL the user owns, and where automations are set up.\n\n## Automations are set up in the Speak AI app\n\nAutomations (a trigger plus steps that run on their own, such as summarizing every new recording or posting to Slack) are created, tested and managed in the Speak AI web app at <https://app.speakai.co>. This connector does not create, change or run automations. When the user asks for one, explain that and point them to the Automations page in the app. Automations the user has already set up keep running on their own.\n\n## Receive Speak events on your own server\n\nRegister an outbound webhook with `create_webhook`. It takes `callbackUrl`, which must\nbe an HTTPS URL, an optional `events` array of event types, and an optional\n`description`.\n\nOver raw HTTP, send your API key on every call, in `x-speakai-key` or as\n`Authorization: Bearer <key>`. There is no access token to fetch.\n\n```sh\ncurl -X POST https://api.speakai.co/v1/webhook \\\n  -H \"x-speakai-key: speak_sk_example_000000000000\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"callbackUrl\": \"https://example.com/hooks/speak\",\n    \"description\": \"Production event receiver\"\n  }'\n```\n\nOr through the CLI, which calls the same tool:\n\n```sh\nspeakai-mcp call create_webhook '{\"callbackUrl\":\"https://example.com/hooks/speak\"}'\n```\n\n**The new id comes back as `data.webhookId`.** Read it from there. Store it, because\n`update_webhook` and `delete_webhook` both require it, and `update_webhook` replaces\nthe whole config, so you must always send `callbackUrl` again even when you are only\nchanging the event list.\n\n### Delivery bodies and idempotent handling\n\nEvery delivery body carries two fields you should rely on:\n\n- `eventType`, which tells you what happened and lets one endpoint serve several\n  subscriptions.\n- `deliveryId`, which identifies this delivery. Speak generates a fresh `deliveryId`\n  per delivery and reuses the same value across retries of that delivery.\n\nThat reuse is the whole reason idempotent handling works. Record every `deliveryId` you\nfinish, and drop a body whose `deliveryId` you have already recorded. Do not key on the\nevent payload contents, because two genuinely separate events can look identical.\n\n```js\n// Express receiver. Returns 200 fast, then does the real work out of band.\nconst express = require(\"express\");\nconst app = express();\napp.use(express.json());\n\nconst seenDeliveries = new Set(); // Use a durable store in production.\n\napp.post(\"/hooks/speak\", (req, res) => {\n  const { eventType, deliveryId } = req.body;\n\n  if (!deliveryId) return res.status(400).send(\"missing deliveryId\");\n  if (seenDeliveries.has(deliveryId)) return res.status(200).send(\"duplicate\");\n\n  seenDeliveries.add(deliveryId);\n  res.status(200).send(\"ok\");\n\n  setImmediate(() => handleEvent(eventType, req.body));\n});\n\nfunction handleEvent(eventType, body) {\n  console.log(\"handling\", eventType, body);\n}\n\napp.listen(3000);\n```\n\nAcknowledge with a `2xx` before you do slow work. A handler that transcribes, calls an\nLLM, or writes to a slow database inside the request is the most common cause of\nretries, and retries are what make duplicate handling necessary in the first place.\n\nUse `list_webhooks` to see everything registered in the workspace before you add\nanother one. Duplicate `callbackUrl` values are a common way to end up processing every\nevent twice.\n\nDocs: <https://docs.speakai.co/mcp/tools/webhooks/create_webhook/>,\n<https://docs.speakai.co/mcp/tools/webhooks/list_webhooks/>,\n<https://docs.speakai.co/mcp/tools/webhooks/update_webhook/>, and\n<https://docs.speakai.co/mcp/tools/webhooks/delete_webhook/>.\n\n## Edge cases that actually bite\n\n**Empty results are normal, not errors.** `list_webhooks` on a new workspace returns an empty list with a success status. Report the empty result. Do not retry it and do not treat it as a failure.\n\n**Permissions and scope.** Every call runs with the permissions of the API key or the OAuth session. A key without webhook access gets a `401` or `403`, not an empty list. Ask the user to check their key at <https://app.speakai.co/developers/apikeys> rather than retrying.\n\n**Ask before destructive calls.** `delete_webhook` stops deliveries and removes its delivery history, and `update_webhook` replaces the whole configuration. Confirm with the user first and say exactly what will change.\n"
}