Shoovoo Docs

Appearance

API and webhooks ​

REST API ​

The API lives under /v1, on your Shoovoo address and, for integrations, on api.shoovoo.com. The full, current reference is generated from the code: open /v1/docs on your Shoovoo address, or fetch /v1/openapi.json.

  • Authenticate with a key created by an Admin under Settings → API Keys (Authorization: Bearer mak_…), or with a signed-in session.
  • A key's scope (read, write or admin) decides what it may do. Some routes are closed to keys.
  • Send an Idempotency-Key header on creating requests so a retry does not duplicate.
  • Add contacts with POST /v1/contacts. Without proof of consent the contact becomes pending and gets a confirmation message. See Consent and double opt-in.

Outbound webhooks ​

An Admin adds endpoints under Settings → Webhooks and chooses which events to receive.

  • The URL must be https and publicly reachable. Addresses with credentials or private addresses are refused.
  • Each event is signed. The signing secret is shown once, when the endpoint is created or its secret rotated. Store it then.
  • Delivery is at least once, so the same event can arrive twice. Use the X-Webhook-Id header to ignore repeats.
  • A failed delivery is retried on a schedule. Send test sends a real webhook.test event, and Delivery log shows each attempt. You can also edit an endpoint, Turn off and Turn on its deliveries, and Rotate secret.

MCP (AI assistants) ​

MCP (the Model Context Protocol) lets an AI assistant such as Claude Code work in your account: look things up, and create drafts. An Admin sets it up under Settings → MCP Server.

  • It starts switched off. Until the platform operator turns MCP on for your account, the address answers "not found" whatever key you use. Ask them to enable it.
  • The page shows the address to connect to (your Shoovoo address followed by /mcp). Tick Include the workflow tools to add ?toolsets=workflow, which offers tools for building campaigns and checking audiences, each named workflow_…. Other toolsets are added the same way, separated by commas.
  • Create a key on the page. The scope is Write by default, which lets the assistant read and create or update drafts and contacts, but not delete or change settings. Read lets it look and nothing else. Admin also lets it delete data and change settings, and it acts without asking you each time, so choose it only when you need that, and revoke the key afterwards.
  • The key is shown once. While it is on screen the setup snippets contain it; copy the Claude Code command or the JSON configuration into your client. Afterwards they show mak_YOUR_KEY in its place.
  • The key is an ordinary API key: it appears under Settings → API Keys, where you can revoke it.
  • Connectors that cannot take a key (for example claude.ai's custom connectors) connect by signing in instead. Add the address above to the connector; it finds Shoovoo's sign-in on its own. You are sent to a Connect page in Shoovoo (sign in first if asked), where you see the connector's name and where you will be returned to, choose what it may do (Write by default; Admin is never preselected) and press Allow. Only an Admin can approve, for the account you are signed in to, so switch account first if you need another.
  • A connector you approved appears under Settings → API Keys as Connector: its name. Revoke it there to disconnect it at once. It stays connected for up to 30 days without being used, and asks you again after that or after you revoke it.
  • A key only offers the tools its scope covers. The workflow tools that write only ever create drafts.

Webhooks from your store ​

A store sends events to Shoovoo, not the other way round. Each is signed with the store's webhook secret. See Connect a store and the custom connector.