Workflow integrations

Workflow integrations connect BlendDuck to collaboration, storage, automation, and AI tools. Social publishing accounts remain in Channels. SMS, WhatsApp, and phone providers are not part of this surface.

Before you start

• Use a BlendDuck Owner or Admin account.
• Ask a Slack administrator to approve installation when the workspace requires it.
• Choose a low-risk Slack channel for the first real test message.
• Never paste Slack credentials or OAuth callback parameters into a support message.

Slack

An owner or admin can open Settings → Integrations → Slack and install the BlendDuck app. After OAuth, choose a channel the app has already joined. BlendDuck requests only:

• channels:read
• groups:read
• chat:write

It does not request Slack message history or permission to post to every public channel. The configuration dialog lists only joined channels.

Use Send test to confirm the selected channel. This sends one real Slack message. BlendDuck does not send approval or publishing notifications unless a workspace event rule explicitly enables them.

Send test is a delivery check, not a general notification preference. If it is ambiguous whether Slack accepted the request, BlendDuck stops for manual review instead of sending the message repeatedly. Check the destination before trying again with a new request.

Cloud content

Status: implemented locally; each deployment must register its own OAuth apps, and live provider verification is still required.

Owners and admins can connect Dropbox, Google Drive, or Notion from Settings → Integrations. Open Manage to browse the connected account and explicitly import a supported item:

• Images and videos are copied into Media Library.
• Text, Markdown, JSON, Google Docs, Google Sheets, and Notion pages are copied into Knowledge Base.

Viewers may browse the available content but cannot import it. BlendDuck keeps the source item and revision with the imported target, so disconnecting an account removes its credential without removing imported content or its source record. Temporary provider download links are not retained.

OneDrive and Canva are listed as Not supported and cannot start an OAuth connection. Their provider implementations are retained for a later release, but neither is part of the current product scope.

Zapier and n8n

Status: the workflow contract is implemented. It uses the existing public API and signed webhooks; BlendDuck does not claim a published marketplace app or create a second workspace identity.

Create one organization API key in Developer → API keys and keep only the scopes used by the workflow. The bearer key already selects its organization, so requests use paths such as /api/v1/posts and never include workspace_id in the URL, query, or body.

For event-driven workflows:

1. Create a Catch Hook in Zapier or a production Webhook node in n8n.
2. Add that HTTPS URL under Developer → Webhooks and select exact events.
3. Store the one-time whsec_v1_… signing secret in the automation tool's credential or secret store, not in workflow JSON.
4. Before side effects, verify Webhook-Signature as HMAC-SHA256 over Webhook-Id.Webhook-Timestamp.rawBody, enforce a five-minute timestamp tolerance, and deduplicate the stable Webhook-Id.

n8n's Webhook node must enable Raw Body. A self-hosted Code-node verifier also needs its runtime to allow the Node crypto module; otherwise verify at a trusted ingress before the workflow. Do not silently continue with an unverified parsed body.

Available recipes are checked against the published OpenAPI and webhook catalog:

In Zapier, use Webhooks by Zapier for the trigger and an API Request action for the API call. In n8n, store Authorization: Bearer … as a Header Auth credential and use an HTTP Request node. Never paste the API key into a node URL or exported workflow.

The repository includes importable references under examples/n8n/: a least-scope channel-read/draft action and a raw-body signed-webhook trigger. Replace their credential placeholders inside n8n; never put an API key or webhook secret into exported JSON. The draft example deliberately cannot publish, and retries reuse one stable business identity.

Production acceptance has exercised the n8n path with only channels:read and posts:write: two action executions resolved to one logical draft with zero provider attempts, and a fresh signed webhook reached the verifier on its first delivery attempt. The same receiver also acknowledges an exact event replay as a duplicate before downstream work. A private Zapier action has also exercised API-key authentication and idempotent draft creation without a provider attempt; one signed Zapier trigger delivery remains the private-run gate.

ChatGPT, Claude, and MCP

All AI clients use the same remote Streamable HTTP resource:

https://blendduck.com/api/mcp

This path performs OAuth discovery, PKCE, consent, refresh, scope checks, and workspace membership checks. It does not accept or reveal a social-provider credential. Start with blendduck:read; request blendduck:write only for a client that should create, schedule, or publish content.

• ChatGPT: create a custom MCP app in Developer mode, enter the MCP address, choose OAuth, scan tools, and review write actions. Availability depends on the current ChatGPT plan and workspace policy.
• Claude Code: run claude mcp add --transport http blendduck https://blendduck.com/api/mcp, then open /mcp and complete browser OAuth.
• Other MCP clients: use the same resource and its protected-resource metadata. The generic setup lives under Settings → MCP.

Current client references: ChatGPT custom MCP apps and Claude Code MCP. Manus is deferred from this release.

Self-hosted setup

Create the provider app and register its exact callback:

${APP_URL}/api/integrations/connect/callback/slack
${APP_URL}/api/integrations/connect/callback/dropbox
${APP_URL}/api/integrations/connect/callback/google-drive
${APP_URL}/api/integrations/connect/callback/notion

Then configure these as server-only secrets:

SLACK_CLIENT_ID=...
SLACK_CLIENT_SECRET=...
DROPBOX_CLIENT_ID=...
DROPBOX_CLIENT_SECRET=...
GOOGLE_DRIVE_CLIENT_ID=...
GOOGLE_DRIVE_CLIENT_SECRET=...
NOTION_CLIENT_ID=...
NOTION_CLIENT_SECRET=...

The Integrations page displays Setup required until the matching client ID and client-secret pair exists. It does not simulate a connected state.

Safety

OAuth state is encrypted and single-use. Access and refresh tokens stay encrypted at rest. Test sends are idempotent; ambiguous delivery failures stop for manual review instead of retrying automatically. Disconnect deletes the local credential. Content imports are bounded, idempotent, and provenance linked; imported copies remain after disconnect. Slack workspace retention still controls messages that already exist there.

You are done when

• Integrations shows Slack as connected.
• The selected destination is a channel the app has joined.
• One test message appears exactly once in that destination.
• The team understands that approval/publishing alerts require a separate event rule.

If something blocks you