Linear | Stoaken Integrations

What it does

A Stoaken webhook sent as a Linear issue creates an issue for one Linear team when a release is submitted for review.
The title is "Review Release v1.4.0 of Brand · Theme". The description (Markdown) says how many changes it has and links to the release in Stoaken.
It uses a personal API key you create. There's no Linear app or OAuth.

Brand Admin on the Brand (webhooks are part of the Team plan).
A Linear account that can create issues in the team. Issues are created as that account.
A personal API key from Settings > Account > Security & access (Linear).
The team's id, a UUID: open the team in Linear, press Cmd/Ctrl+K and choose Copy model UUID.

Create the API key and copy it.
In Stoaken, go to Settings > Webhooks and choose Add a webhook:
- Send as: Linear issue (the address fills in as https://api.linear.app/graphql)
- API key: the key. It's stored encrypted and never shown again.
- Team id: the UUID
- Events: Release submitted for review (the only one this format takes).

The request is the GraphQL mutation issueCreate(input: { teamId, title, description }) to https://api.linear.app/graphql, with the key as Authorization: <API key> (no "Bearer").
Linear can answer 200 with an errors list. Stoaken reads the answer and counts that (or success: false) as a failure, with Linear's message in Recent deliveries.
No labels, assignee, priority or project are set; the team's defaults apply.
Stoaken only sends the key to https://api.linear.app/graphql, and the database refuses any other address. More on formats: /docs/webhooks.

On the webhook, choose Send test. Stoaken looks the team up (team(id:)) instead of creating an issue: it passes when the key works and can see the team.
In the webhook lab, choose Send a sample with Release submitted for review. A real issue marked [Test] is created; delete it afterwards.
Submit a release for review and open the new issue's link.

Authentication required: the key is wrong or was revoked. Make a new one and add the webhook again.
That team wasn't found for this API key: the team id is wrong, or the key's account isn't in that team.
Entity not found or other GraphQL errors: Linear's message shows in Recent deliveries.
429 or a rate-limit error: Linear's rate limit. Stoaken retries the delivery later.

Only Release submitted for review makes an issue. Stoaken doesn't comment on or close it when the release is published or rejected, because it doesn't keep track of the issue it made.
One team per webhook; a Brand has at most 10 webhooks.
The key acts as the person who made it, with their access; it stops working if they leave the workspace.
Failed deliveries retry for about a day (/docs/webhooks).