Zapier: Pivot’s Zapier Integration

Overview

The Pivot Zapier integration allows users to connect Pivot with 7,000+ apps through Zapier’s automation platform. It is built using the Zapier Platform CLI and lives in apps/zapier/ within this repository.

The integration leverages the Pivot REST API (api.pivot.app) for all data operations and the webhook infrastructure for instant triggers. Authentication uses the same API key mechanism as the REST API — Bearer token with pivot_-prefixed keys.

Architecture


Zapier Cloud ←→ Pivot Zapier App ←→ Pivot REST API ←→ Internal Services
                                         ↓
                                   Webhook System (NATS → Cassandra → HTTP delivery)

Triggers (REST Hooks)

Triggers use Zapier’s REST Hook pattern. When a user enables a trigger:

subscribeHook calls POST /v1/organizations/{orgId}/webhooks to create a webhook pointing at Zapier’s callback URL
Pivot’s webhook consumer delivers events to Zapier in real-time
unsubscribeHook calls DELETE to clean up when the user disables the Zap

Supported webhook event types:

message_sent — New message in a room or space
message_deleted — Message deleted
message_edited — Message edited
room_recording_published — Recording available
room_recording_transcript_published — Transcript available
block_response_sent — Block response submitted

Each trigger supports scoping to a specific room, space, or block via the webhook subscription’s subject_type and subject_id. Message triggers also support room_types filtering.

All triggers include a performList function (required for public Zapier apps) that fetches recent data from the REST API as sample data.

Actions (Creates)

Actions wrap REST API write endpoints. They cover:

Messaging: Send Message (v2 API)
Spaces: Create, Update, Copy, Hide
Rooms: Create (v2), Update (v2)
Members: Add space members, Add room members
Invites: Invite to space/room by email
Labels: Create, Update, Delete, Set space labels
Groups: Add/Remove members, Add group to space
Blocks: Create response, Send response
Roles: Create space role

Searches

Searches wrap all REST API GET endpoints, giving users access to:

Spaces, Rooms, Messages, Threads
Members, Roles
Blocks, Block Responses, Assignment Blocks
Groups, Group Members
Labels
Recordings
User Context
Webhooks

Dynamic Dropdowns

Where list endpoints exist, input fields use Zapier’s dynamic property to provide dropdown selection. Hidden triggers power these dropdowns:

list_spaces → Space selection
list_rooms → Room selection (scoped to a space)
list_groups → Group selection
list_labels → Label selection

Fields without a list endpoint (e.g. block_id, message_id) fall back to plain text input for the user to paste an ID.

Development

Prerequisites


npm install -g zapier-platform-cli

Local Development


cd apps/zapier
pnpm nx build pivot-zapier   # Compile TypeScript (src/ → dist/)
pnpm nx test pivot-zapier    # Run vitest tests
npx zapier validate          # Validate app structure

Deployment

Deployment is automated via GitHub Actions (.github/workflows/zapier-deploy.yml). On merge to main, when apps/zapier/** changes, the workflow builds, validates, and runs zapier push --skip-dep-install using the ZAPIER_DEPLOY_KEY secret in the zapier-deploy environment.

Manual deployment:


cd apps/zapier
pnpm nx build pivot-zapier
npx zapier push --skip-dep-install

Testing

The test suite validates:

All triggers, creates, and searches are registered with correct keys
All modules have perform functions and sample data
Middleware correctly adds auth headers and handles errors
Authentication configuration is correct

Dependencies

Pivot REST API — All data operations go through api.pivot.app
Webhook Infrastructure — Instant triggers rely on the webhook consumer (see Rest)
zapier-platform-core — Zapier’s runtime SDK

Security

API keys are stored securely by Zapier and sent as Bearer tokens
No secrets are stored in the Zapier app code
Webhook payloads are signed with HMAC (handled by Pivot’s webhook delivery)