Zapier | Stoaken Integrations

What it does

Trigger: a standard Stoaken webhook posts to a Webhooks by Zapier > Catch Hook address. The Zap runs on release.pending_approval, release.published and release.rejected (see /docs/webhooks).
Act: later steps post to a channel or create a task in any app Zapier connects to. A Webhooks by Zapier action (GET or Custom Request) can call the Stoaken REST API with an API key (see /docs/api).

Zapier Professional, Team or Enterprise. Webhooks by Zapier is a premium app, so it isn't on the Free plan; premium apps also work during a trial (plans).
Brand Admin in Stoaken, on the Team plan, to add the webhook.
To call the API: a Stoaken API key from Settings > API keys. It acts as the person who made it, with their roles. Reads work on every plan; writes need a paid plan.

In Zapier, create a Zap with the trigger Webhooks by Zapier, event Catch Hook. Leave Pick off a child key empty, so type comes through.
Copy the address from the trigger's Test tab. It looks like https://hooks.zapier.com/hooks/catch/…/…/.
In Stoaken, go to Settings > Webhooks, choose Add a webhook, set Send as to Stoaken event, paste the address and pick the events you want.
In the webhook lab on the same page, use Send a sample with Release published. Then choose Test trigger in Zapier: you should see fields such as Type, Data Version, Data Release ID, Data Changes Total and Data Is Breaking.
Add a Filter by Zapier step: Type, (Text) Exactly matches, release.published. Use Paths instead to handle several events in one Zap.
Add your action, then publish the Zap.

To call the API from a step, add Webhooks by Zapier > GET:

URL:      https://www.stoaken.com/api/releases/{{Data Release ID}}
Headers:  Authorization | Bearer stk_…

Recipes

Release published, post to a channel: filter on release.published, then Slack Send Channel Message (or Teams): Tokens v{{Data Version}} are live: {{Data Changes Total}} changes, breaking: {{Data Is Breaking}}.
Release published, create a task: filter on release.published and Data Is Breaking is true, then create a task in Jira, Asana, Linear or similar: Update to tokens v{{Data Version}}.
Release needs review, notify reviewers: filter on release.pending_approval, then message the reviewers' channel with https://www.stoaken.com/review/{{Data Release ID}}. Reviewers approve or reject there.
Release rejected, tell the author: filter on release.rejected, GET the release, and send its rejection_reason to the person in created_by.

What the API gives you

The event carries ids, the version and change counts, not names. GET /api/themes/{id} and GET /api/brands/{id} return the theme's and Brand's name.
GET /api/releases/{id} returns status, created_by, approved_by, rejection_reason and change_summary. Add /changes for every change, mode by mode, or /timeline for who sent, approved or rejected it and when.
GET /api/releases/{id}/export?format=css returns the release as a file.
Writes use Custom Request with Content-Type: application/json and an Idempotency-Key header, for example {{Data Event ID}}-submit. The API can propose a release (POST /api/themes/{id}/releases) and send a draft for review (POST /api/releases/{id}/submit). That's all it can do with releases.

Checking it came from Stoaken

Catch Hook doesn't pass on request headers, so it can't check Stoaken's signature. Treat the hook address as the secret: only people who can see it, such as Brand Admins in Stoaken, can post to it.
For an extra check you can rotate, add a long random value to the address you paste into Stoaken, like …/catch/…/…/?key=RANDOM. Catch Hook puts query parameters under querystring, so the Filter step can also require Querystring Key to exactly match it.
Catch Raw Hook keeps the headers and the raw body (2 MB at most), and Code by Zapier runs Node.js 22 with its standard library. So you could run the check from /docs/webhooks in a Code step. We haven't tested this in Zapier.

Send test on the webhook sends a ping. Zapier should answer 200, and your Filter should stop the run (Type is ping).
Send a sample with each event you use, then test every step in the Zap editor.
Publish the Zap and send a real release for review.

Webhook switched off in Stoaken: a Zap that's off or deleted answers 404. Stoaken retries, and after 5 failed deliveries in a row it switches the webhook off. Turn the Zap on, then turn the webhook back on in Settings > Webhooks.
Events lost after turning a Zap off: Zapier can keep answering 200 for a few hours after a change, so Stoaken counts those as delivered.
The address stopped working: a Zap transferred to another Zapier user gets a new address. Paste the new one into the webhook.
401 from the API: the header must be Authorization with the value Bearer stk_… (one space).
400 idempotency-key-required: a write without an Idempotency-Key header. 403 on a write: the key's owner lacks the role, or you're on the Free plan.
429: a key can make 120 requests a minute and 60 writes an hour.

Stoaken's signature isn't checked unless you build the Catch Raw Hook and Code step yourself.
Nothing in Zapier can approve, reject or publish a release. People do that in Stoaken.
Deliveries can arrive more than once. Data Event ID is the same on every retry, so use it to skip repeats.
The API key sits in the Zap step, and anyone who can edit the Zap can read it. Use a key from someone with only the roles the Zap needs.