The workspace URL receives webhooks. For everything else, use an API token. A token acts as you, so keep it out of public code.
Create a token
In the Hook app, open Settings → API tokens, or use the web app. Name it, and copy the hk_… secret; it is shown once. You can have 20 tokens, and revoking one stops it at once. A token cannot create other tokens.
Publish
Send the Hook-* headers or a JSON body to /api/publish, with the token as a Bearer header. Add a topic to the path.
curl https://gethook.app/api/publish/deploys \
-H "Authorization: Bearer hk_…" \
-H "Content-Type: application/vnd.hook.message+json" \
-d '{ "title": "Deployed", "message": "api v1.8.0", "priority": 3 }'The token is removed before the request is stored, so it never shows in your inbox.
Endpoints
All take Authorization: Bearer hk_…. The full machine-readable list is at/openapi.json.
| Method | Path | What it does |
|---|---|---|
| POST | /api/publish[/:topic] | Send a message. Same fields as Publishing messages. |
| DELETE | /api/messages/:id/notification | Remove a delivered notification. |
| PUT · DELETE | /api/live-activity/stream/:key | Start or update, or end, a Live Activity. |
| GET | /api/live-activity/streams | List streams. |
| PUT · DELETE | /api/metrics/:key | Set or delete a widget metric. |
| GET | /api/metrics | List metrics. |
| POST | /api/badge | Set the app icon badge. |
| POST | /api/approvals | Ask for an approval. |
| GET | /api/approvals/:id?wait=25 | Read an approval, waiting up to 50 seconds. |
| GET · POST | /api/tokens | List or create tokens. Not with a token. |
Details: messages, Live Activities,metrics and badge, approvals.
Teams and channels
Invite up to 10 people to your workspace. Members get its notifications, Live Activities, widget metrics and approvals on their own iPhones; any member can answer an approval. Set it up in the app (Settings → Team), in the web app, or with the API:
GET /api/teammembers, open invite codes, channels, and the teams you joined.POST /api/team/invitesa code valid for 7 days. The other person sendsPOST /api/team/joinwith{ "code": "…" }.DELETE /api/team/members/:userIdremoves a member;DELETE /api/team/memberships/:workspaceIdleaves a team.PUT /api/team/channels/:topicwith{ "member_ids": ["…"] }sends that topic to only those members (you always get it);nullmeans everyone.
Errors
Errors are JSON: { "ok": false, "error": "…" }.
400a field is invalid.invalid_message_formatandinvalid_content_statename the field.401 unauthorizedthe token is missing, wrong or revoked.409 workspace_missingcreate a workspace in the app first.409 no_deviceno iPhone can show a Live Activity yet.429rate limited. Wait and retry.
Rate limits
- 60 webhooks a minute per workspace, including
/api/publish. - 120 Live Activity and metric calls a minute per user.
Something wrong on this page? Email office@swiftapps.us.