Make | Stoaken Integrations

What it does

Trigger: a standard Stoaken webhook posts to a Make Webhooks > Custom webhook address. The scenario runs on release.pending_approval, release.published and release.rejected (see /docs/webhooks).
Act: later modules post to a channel or create a task. The HTTP > Make a request module can call the Stoaken REST API with an API key (see /docs/api).

Before you start

A Make account. Custom webhook and HTTP are Make's own apps, and Make's pages list no plan restriction for them. Every run uses credits, and the Free plan has 1,000 a month.
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.

Setup

In a new scenario, add Webhooks > Custom webhook. Next to Webhook, choose Add, name it and save. Copy the address (like https://hook.eu2.make.com/…).
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 Make, choose Run once. In Stoaken's webhook lab, use Send a sample with Release published. Make learns the fields from it: type, data.version, data.release_id, data.changes.total, data.is_breaking and the rest.
Set a filter on the link after the webhook: type, Text operators: Equal to, release.published. Use a Router with one filtered route per event to handle several.
Add your modules, then switch the scenario on with scheduling set to Immediately.

To call the API, add HTTP > Make a request:

URL:             https://www.stoaken.com/api/releases/{{1.data.release_id}}
Method:          GET
Headers:         Authorization = Bearer stk_…
Parse response:  Yes

Make suggests keeping keys in a keychain (Authentication type: API key) rather than in a header, so they don't show in the scenario. If you do, make the keychain send Authorization: Bearer stk_… as a header.

Configuration

Recipes

Release published, post to a channel: filter on release.published, then Slack Create a message (or Teams): Tokens v{{1.data.version}} are live: {{1.data.changes.total}} changes, breaking: {{1.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, monday.com or similar: Update to tokens v{{1.data.version}}.
Release needs review, notify reviewers: filter on release.pending_approval, then message the reviewers' channel with https://www.stoaken.com/review/{{1.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 need Body content type application/json and an Idempotency-Key header, for example {{1.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

We have no tested way to check Stoaken's signature in Make. With Get request headers and JSON pass-through on, Make gives you the headers and the body as text, and its sha256() function takes a key for an HMAC. We haven't confirmed it can use Stoaken's key (the decoded bytes after whsec_) or that the text matches the raw body byte for byte.
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 https://hook.eu2.make.com/…?key=RANDOM. Make puts query parameters in the same bundle as the body, so the first filter can also require key to equal it.
Leave Make's API Key authentication off: it reads the key from an x-make-apikey header, which Stoaken doesn't send. Leave IP restrictions empty too, because Stoaken doesn't send from fixed addresses.

Try it

Send test on the webhook sends a ping. Make should answer 200 Accepted, and your filter should stop the bundle (type is ping).
Send a sample with each event you use while the scenario runs once, and check each module's output.
Switch the scenario on and send a real release for review.

Troubleshooting

Fields missing in the mapping panel: run once and send a sample again, so Make relearns the data structure. A ping has no version.
400 Queue is full: Make holds at most 667 waiting requests per 10,000 credits a month. Switch the scenario on, or set it to run immediately.
410 Gone: Make switches off a hook that's been detached from every scenario for 5 days. Attach it again or make a new one and update the webhook address.
Webhook switched off in Stoaken: after 5 failed deliveries in a row Stoaken switches it off. Fix Make, then turn the webhook back on in Settings > Webhooks.
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.

Limits

Stoaken's signature isn't checked; the hook address (and your key, if you add one) is what you rely on.
Nothing in Make 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.
Make accepts 300 webhook requests per 10 seconds and bodies up to 5 MB, far above what Stoaken sends.