# Zapier and n8n: automate around reviews and publishes

Source: https://versodocs.com/docs/automations

Connect VersoDocs to thousands of apps. **Triggers** fire when proposals are opened or reviewed and when a version is published (every plan). **Actions** read the Current version, search, propose changes and comment, with the same plans and scopes as the [REST API](https://versodocs.com/docs/api.md).

## Plans

|   | Free | Team | Pro |
| --- | --- | --- | --- |
| Zapier + n8n triggers (key review events) | ✓ | ✓ | ✓ |
| Zapier + n8n triggers on every event | — | ✓ | ✓ |

Actions: reading the Current version works on every plan; search needs Team; comments and advisory reviews need Team; proposing changes with an API key needs Pro.

## Connect

1. In VersoDocs, an owner or admin creates an API key in **Settings → Developer** (scope `docs:read`, plus `proposals:review` or `docs:propose` for those actions).
2. **Zapier:** add the **VersoDocs** app, paste the key and your organization slug (the part after `/org/` in VersoDocs URLs).
3. **n8n:** install the community node `n8n-nodes-versodocs` (**Settings → Community Nodes**), create a **VersoDocs API** credential with the key, organization slug and base URL.
4. Pick a trigger. If the key can see several workspaces, choose the **workspace** to watch.

## Triggers

| Event | Fires when | Plan |
| --- | --- | --- |
| `version.published` | A document is published as a new version. | All plans |
| `version.acknowledged` | A member confirms they have read the current version of a document. | Team+ |
| `document.created` | A new document is created in a workspace. | Team+ |
| `document.updated` | A document is renamed or moved to another folder. | Team+ |
| `document.deleted` | A document is permanently removed. | Team+ |
| `document.commented` | Someone (a member, an agent or a share-link guest) comments on a published version of a document or replies in a thread. | Team+ |
| `proposal.opened` | A reviewer is asked to review proposed changes to a document. | All plans |
| `proposal.updated` | An open proposal’s title, description or content is revised through the API. | Team+ |
| `proposal.commented` | Someone (or an agent) comments on a proposal or replies in a thread. | Team+ |
| `proposal.verdict_submitted` | A reviewer approves a proposal, asks for changes, or leaves a comment. | All plans |
| `proposal.published` | A proposal is published: its working copy becomes the new current version. | Team+ |
| `proposal.closed` | A proposal is closed by its author without publishing. | Team+ |
| `review.requested` | Someone asks an external reviewer bot (API key) to review a proposal. | Team+ |
| `ai_review.completed` | A hosted AI reviewer posted its (advisory) review on a proposal. | Team+ |
| `ai_review.failed` | A hosted AI reviewer gave up after retries (e.g. bad key, provider down). | Team+ |

Each delivery is `{ event, created_at, data }` with the same `data` as workspace webhooks, signed with `x-versodocs-signature-v2`. Turning a Zap or workflow off removes its subscription; revoking the API key stops all of its subscriptions.

## Actions

| Action | REST endpoint | Plan |
| --- | --- | --- |
| Get document (Current version) | `GET docs/{id}/current`, `GET docs/by-path` | All plans |
| Search approved docs | `GET search` | Team+ |
| Comment on a proposal | `POST proposals/{id}/comments` | Team+ |
| Leave an advisory review | `POST proposals/{id}/reviews` | Team+ |
| Propose a change (never publishes) | `POST docs/{id}/proposals` | Pro |

## Subscription API

Zapier and n8n use these endpoints; any automation tool can too. API key, `docs:read` scope.

### POST /api/v1/orgs/{org}/webhooks

Minimum plan: All plans

Query parameters:

| Name | Type | Description |
| --- | --- | --- |
| `target_url` (required) | `string` | HTTPS URL that receives deliveries. |
| `events` (required) | `string[]` | Event names. Free: `proposal.opened`, `proposal.verdict_submitted`, `version.published`. |
| `workspace` | `string` | Workspace slug or id. Required when the key sees several workspaces. |
| `description` | `string` | Label shown in Settings. |

Returns `201 { id, target_url, events, workspace, created_at, secret }`. The `secret` (for signature checks) is shown only here. A Team event on Free answers `402` with `locked_events`.

### GET /api/v1/orgs/{org}/webhooks

Minimum plan: All plans

Subscriptions created through the API in the key’s workspaces.

### DELETE /api/v1/orgs/{org}/webhooks/{id}

Minimum plan: All plans

`204` when removed.

### GET /api/v1/orgs/{org}/webhooks/samples?event={name}

Minimum plan: All plans

Up to 3 recent deliveries for that event (or one example), for building and testing a Zap or workflow.