What the Zapier integration does

Zapier links Huddlekit to other apps without code. A Zap can start when someone leaves a comment or when a comment's status changes, and a Zap can create comments or change their status. For an overview, see the Zapier integration page.

Unlike Linear or Slack, there is no connection to make on the Huddlekit side. Zapier signs in with a workspace API key, so setting it up means creating a key in Huddlekit and pasting it into Zapier.

Who can set it up

Zapier connects with an API key, and API keys are on the Team plan. Only workspace owners and admins can create them. See Understanding plans and pricing.

Connect Zapier

Huddlekit's Zapier app is invite-only for now, so it doesn't show up in Zapier's app search until you've accepted the invite. The setup dialog in Huddlekit has the link.

Open Integrations in your workspace sidebar.
Find Zapier and click Set up. The dialog lists the steps.
Click Open Huddlekit in Zapier and accept the invite in the tab that opens.
Back in the dialog, click Create an API key. The key dialog opens with Read and write already chosen under Access. Give the key a name and click Create key.
Copy the key. It is shown once and cannot be retrieved later, so copy it before you click I've saved it.
In Zapier, add Huddlekit to a Zap, and paste the key into the API key field when Zapier asks you to connect.

Zapier names the connection after your workspace. A key belongs to one workspace, so to use Zapier with a second workspace, create a key there and add a second connection.

Which access level to choose

Read only — lists projects and comments, and cannot change anything. It won't work with Zapier: both triggers and both actions need write access, so Zapier refuses a Read only key when you connect.
Read and write — also creates comments, changes their status and manages webhook subscriptions. This is the one Zapier needs, and the one Create an API key in the Zapier dialog chooses for you.

If you create the key from Create key in the API keys section instead, it starts on Read only, so change it.

Triggers need write access because turning on a Zap with a Huddlekit trigger creates a webhook subscription in your workspace.

Triggers

New Comment — triggers when someone leaves a new comment.
Comment Status Changed — triggers when a comment's status changes. It includes the previous status as well as the new one.

Both work for comments on websites, web apps and media projects, and private comments are sent too. Each one carries the comment's Comment ID, number, title, text, status, author name and a permalink back to the comment, plus the Surface (website, webapp or document) and the full comment with its page. Comments left on websites and web apps also carry the screenshot and browser details. Use Comment ID, not ID, when a later step needs the comment: ID identifies the event.

Huddlekit sends each event to Zapier within moments, so Zapier doesn't have to poll for it. A new website or web app comment waits about ten seconds first, so its screenshot can go with it. When you test a trigger while building a Zap, Zapier loads your three most recent comments as samples, in the same shape a live event has. Samples for Comment Status Changed are recent comments rather than real status changes, so their previous status always shows as open.

Each Zap's trigger also appears under Webhooks on the Integrations page as Subscription via API key followed by part of the key's ID. Every Zap using the same key has the same name, so tell them apart by their hooks.zapier.com address. Each has a Delivery log you can check if events aren't arriving. For how deliveries and retries work, see Setting up webhooks.

Actions

Create Comment

Creates a comment on a website, web app or media project.

Project (required) — pick one from the dropdown. Web apps and media projects are marked "(web app)" and "(document)".
Comment (required) — the feedback itself, up to 10,000 characters.
Page path (projects and web apps) — which page it is about, such as /pricing. Defaults to / on a website project. On a web app, leave it empty to use the path of the page URL.
Page URL (web apps) — the full address of the page on your site where the widget runs.
Page title (web apps) — the title of that page.
Page number (documents) — which page, starting at 1.
Video time in seconds (documents) — where in the video. Videos only.
Status — open, in-review, in-progress or resolved. Defaults to open.

Only the fields that fit the chosen project are sent, so leftover web app or media fields don't cause errors on a website project.

Update Comment Status

Changes a comment's status.

Comment ID (required) — usually mapped from the Comment ID field of a New Comment trigger.
Surface (required) — website, webapp or document. It's preset to website, so map it from the trigger's Surface field. The wrong surface gives a "Not found" error.
Status (required) — open, in-review, in-progress or resolved.

A Zap can't edit a comment's text or delete a comment. Neither can the REST API.

Search: Find Project

Finds a website, web app or media project by Name. An exact name match, ignoring capitals, wins. If there is none, it returns projects whose names contain what you typed. When several match, the Zap uses the first, and website projects come first, so give web apps and media projects names of their own.

Use it to choose the project for Create Comment from an earlier step instead of a fixed dropdown choice. If you map the Project field from another step, the value must look like website:<id>, webapp:<id> or document:<id>. Find Project returns it in that form as Ref.

Two-way Zaps and comment authors

A Zap that both reads and creates comments won't loop, as long as its trigger and actions use the same Huddlekit connection. Huddlekit never sends a trigger the comments or status changes made with the API key that set it up.

Comments created by a Zap are posted by a guest named API, so nobody mistakes them for a client's feedback. Every event also has a source field: app for a change made in Huddlekit or synced back from Slack, Linear, ClickUp or Notion, mcp for one made by an AI tool over MCP, and connector: followed by the key's ID for one made with an API key.

Disconnecting Zapier

Turning a Zap off in Zapier removes its subscription from Huddlekit, as long as its key still works.
Revoking the key cuts Zapier off completely. Under API keys, open the key's ⋯ menu and click Revoke key. There's no confirmation step, and it takes effect straight away. Calls made with it stop working, and the triggers it set up stop sending. Under Webhooks they show Key revoked and "Its API key no longer works. Remove it and connect again." They can't be re-enabled, so remove them. To reconnect, create a new key, reconnect Huddlekit in Zapier with it, and turn each Zap off and on again.

Revoking a key and turning a Zap off work on every plan.

If your workspace leaves the Team plan

This also happens while a payment is past due. The key stays listed with a Paused badge, and every Zapier step that uses it fails with "This feature requires the Team plan." Triggers stop firing, and comments left in the meantime are not sent later. Once the workspace is back on Team, the same key works again.

Troubleshooting

This API key is Read only. Zapier needs a key with Read and write access., or This key lacks the "write" scope on a connection made earlier — the key was created as Read only. Create a Read and write key and reconnect Huddlekit in Zapier with it.
Invalid or revoked API key — the key was revoked, or it isn't one Huddlekit issued. Keys created in Huddlekit don't expire. Create a new one.
Could not verify the API key. Please retry. — Huddlekit couldn't check the key just then. It doesn't mean the key is wrong, so try again.
Send your key as: Authorization: Bearer hk_live_… — the key wasn't pasted exactly. A key is hk_live_ followed by 64 characters, with nothing missing or added.
This feature requires the Team plan. — see If your workspace leaves the Team plan.
Pick a project from the dropdown… — the Project field was mapped from a step that doesn't return a website:<id>, webapp:<id> or document:<id> value. Use Find Project and map its Ref.
Not found on Update Comment Status — the Surface doesn't match the comment, ID was mapped instead of Comment ID, or the comment is in another workspace.
429 (Too Many Requests) — each key can create 30 comments and change 30 statuses a minute, and make 200 lookups a minute on each endpoint. The response says how many seconds to wait, and Zapier tries again later. See Using the REST API.

Connecting Zapier