Slack

The Hamstik Slack Application brings selected Work Item activity into Slack and lets explicitly linked users work with Hamstik without creating a second authorization system. Slack is a first-party Hamstik Application and is in Preview while live workspace acceptance is completed.

What v1 supports

Connect one or more Slack workspaces to one Hamstik Organization.
Map a Hamstik Project to a bot-accessible Slack channel.
Notify on Work Item creation, assignment or reassignment, status changes, priority changes, sprint changes, comments, and supported mention events.
Filter a mapping with the existing project-scoped SqueakQL syntax.
Use Block Kit Work Item cards with Open in Hamstik and Comment actions.
Explicitly link a Slack user to a Hamstik account, then use /hamstik to view, search, create, and comment according to normal Hamstik permissions.

Slack channel membership is not Hamstik authorization. Archived Projects do not deliver. If a deployment classifies a Project as private or restricted, detailed Slack mappings, tests, reconciliation, and queued delivery all fail closed; a private Slack channel is not an authorization substitute.

Requirements

An Organization administrator needs:

Access to the Organization’s Settings → Apps page.
A Slack App created in the target Slack workspace or Slack App management area.
The Hamstik deployment’s global Slack settings configured by an operator.
Permission to invite the Hamstik bot to each destination channel.

One Slack workspace connection is owned by exactly one Hamstik Organization. Enterprise or BillingAccount membership does not share a connection with other Organizations.

Install Slack

In Hamstik, open the Organization’s Settings → Apps page.
In the Slack Preview card, choose Connect Slack.
Review the Slack consent screen and choose the intended workspace.
Return to Hamstik. The connection card records the workspace name, domain, bot identity, granted scopes, connection health, and last delivery state.
Invite the Hamstik bot to every destination channel before creating a mapping. For example, in Slack use /invite @Hamstik in the channel.

The administrator can connect another workspace, reconnect a workspace after consent changes, disable it temporarily, or disconnect it. Disconnect disables its mappings, removes its encrypted bot credentials, and attempts provider-side token revocation. It does not delete Hamstik Work Items or audit history.

Configure the Slack App

Configure the Slack App with these exact production URLs:

Slack setting	URL
OAuth redirect URL	`https://hamstik.com/api/apps/slack/callback`
Events API request URL	`https://hamstik.com/api/apps/slack/events`
Slash command request URL	`https://hamstik.com/api/apps/slack/commands`
Interactivity request URL	`https://hamstik.com/api/apps/slack/interactions`

The manifest deliberately subscribes to no broad Slack message-history events. The Events API endpoint supports signed URL verification and narrowly scoped future events. Thread replies remain Slack-only discussion in v1.

Requested scopes

Hamstik requests these bot scopes and no user-token or admin scopes:

Scope	Why Hamstik needs it
`commands`	Receive `/hamstik`.
`chat:write`	Send mapped notifications, test notifications, and private responses.
`channels:read`	List public channels that can be selected after the bot is added.
`groups:read`	List private channels that the bot can access.
`users:read`	Resolve a Slack identity for the explicit linking flow.
`users:read.email`	Allow a verified Slack email to appear as a non-binding account suggestion when available.
`team:read`	Capture and validate workspace identity metadata.

Hamstik does not request Slack admin, message history, workspace search, file, impersonation, customized-message, arbitrary user-token, or broad public-channel posting permissions. The bot must be invited to a destination channel.

Project and channel mappings

In the connected workspace card, use Project → channel notifications:

Select a Hamstik Project.
Select a channel returned as available to the bot.
Choose event categories.
Optionally enter a valid SqueakQL filter, such as priority = 'HIGH'.
Choose Add mapping.

The selected Project is always the candidate and authorization boundary. A filter narrows matching Work Items; it cannot expand the Organization or Project scope. Hamstik validates the filter before saving and reports parser or validation errors in the form.

Supported event categories are Work Item created, assigned/reassigned, status changed, priority changed, sprint changed, comments, and supported mentions. Hamstik uses durable domain notification events rather than posting for every database row update. Each mapping has independent enabled state and delivery health. Send test posts a metadata-only confirmation and does not include Work Item data.

Link a Slack user

Before a Slack user can view data, search, see My Work, create a Work Item, or add a comment, they must explicitly link their Slack user to a Hamstik account:

Run /hamstik link.
Open the private Link Hamstik account action.
Sign in to Hamstik normally.
Confirm the Slack workspace and Slack user shown on the page.
Return to Slack.

The link is short-lived, one-time, scoped to the Slack workspace connection, and audited. A matching email can suggest an account but never links automatically. Passwords and personal access tokens are never sent through Slack. Run /hamstik unlink, then /hamstik unlink confirm, to remove your own link.

`/hamstik` commands

All command results are ephemeral/private by default when used in a shared channel. Results are bounded and use links rather than dumping a large result set.

Command	Behavior
`/hamstik help`	Show concise command help.
`/hamstik link`	Start explicit account linking.
`/hamstik unlink`	Explain the confirmation step.
`/hamstik unlink confirm`	Remove the current user’s link.
`/hamstik create`	Open a small modal for an authorized Project key, title, description, and priority.
`/hamstik view HAM-123`	Show an authorized Work Item card. Inaccessible items use generic not-found behavior.
`/hamstik search <SqueakQL>`	Run the canonical SqueakQL query with the linked user as actor and show a bounded result set.
`/hamstik my-work`	Show a bounded set of open Work Items assigned to the linked user.
`/hamstik comment HAM-123`	Open a comment modal and create the comment as the linked Hamstik user after authorization.

The Comment button on a Work Item card uses the same comment path as the command. Slack retries do not create duplicate Work Items or comments.

Security and reliability

Every Slack POST callback validates the original raw request body, Slack’s five-minute request timestamp, and the v0 HMAC-SHA256 signature. Unsigned, malformed, stale, or tampered requests are rejected. Signed requests are acknowledged quickly; durable App inbox and worker jobs perform slow reads, mutations, and notifications afterward. Modal opening is the only provider call kept synchronous because it requires Slack’s short-lived trigger_id.

Slack identifies a Slack user, but Hamstik identifies the effective actor. All reads and mutations use Hamstik’s existing Organization, Project, Work Item, and mutation authorization services. Slack workspace tokens never grant Hamstik authority.

Tokens are encrypted with Hamstik’s existing App secret mechanism. OAuth state, link tokens, inbound event IDs, command hashes, mapping/event ledger rows, and bounded App job retries protect against CSRF, replay, duplicate delivery, and worker restarts. OAuth codes, access tokens, refresh tokens, signing secrets, response URLs, account-link tokens, and sensitive raw Slack payloads are not logged. Account-link bearer tokens are placed in a URI fragment, removed from the address bar, and submitted only in a same-origin JSON request body; they do not appear in the HTTP request target seen by ingress access logs.

Operator configuration and Doctor

Set these server-side variables; never put workspace tokens in .env:

SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
SLACK_SIGNING_SECRET=
SLACK_TOKEN_ROTATION_ENABLED=false
HAMSTIK_SLACK_WORKER_BATCH_SIZE=10
HAMSTIK_SLACK_WORKER_POLL_MS=1000
HAMSTIK_SLACK_MAINTENANCE_INTERVAL_MS=300000

Set SLACK_TOKEN_ROTATION_ENABLED=true only when token rotation is enabled in the Slack App. The worker stores refreshed access and refresh tokens atomically. The deployment also needs the usual HAMSTIK_APP_SECRET_KEY shared by the web and worker processes.

The admin Doctor includes Slack global configuration, encrypted-secret, workspace identity, required-scope, rotation, queue, and mapping-integrity checks. Diagnostics report actionable non-secret error codes only.

On the external production Caddy instance for hamstik.com, ensure access-log output for the exact callback path GET /api/apps/slack/callback omits or redacts the complete query string. The query contains the temporary OAuth code and one-time state; Caddy must still forward both parameters unchanged to Hamstik. This repository does not install, configure, validate, reload, or restart that external ingress.

Troubleshooting

Symptom	Action
Workspace says action required	Review granted scopes, then use Reconnect.
Channel is not selectable	Invite the Hamstik bot to the channel; archived or inaccessible channels are excluded.
`not_in_channel` delivery error	Invite the bot, then use Send test.
Invalid or revoked token	Reconnect the workspace; Doctor reports the non-secret provider error.
A Work Item is not returned	Confirm the linked Hamstik account has normal access to the Project and Work Item. Slack does not reveal inaccessible items.
SqueakQL filter will not save	Use the existing SqueakQL syntax and keep the filter project-scoped.
Notifications are delayed	Check the Slack mapping health and Doctor’s queue check; temporary Slack failures and `Retry-After` are retried with bounded backoff.
A Slack thread reply does nothing in Hamstik	This is expected in v1. Use the Comment button or `/hamstik comment`.

Live acceptance checklist

The following requires a real Slack development workspace and configured credentials:

OAuth install and reconnect; confirm workspace and bot metadata.
Verify the granted scope list matches the reviewed manifest.
Link and unlink a Slack user; verify the explicit confirmation and audit event.
Run help, create, view, search, My Work, and comment commands.
Map a public Project to an invited bot channel and send a test notification.
Trigger each enabled notification category and validate a SqueakQL match and non-match.
Remove the bot from a channel and confirm actionable delivery health.
Revoke a token and confirm reconnect/action-required behavior.
Disconnect the workspace and confirm mappings stop delivering.
Run the admin Doctor checks with a healthy and a broken connection.

Deferred from v1

Direct status or assignment mutation, arbitrary Work Item editing, Slack thread reply synchronization, comment mirroring, unrestricted conversation mirroring, acting as a Slack user, AI/LLM assistant behavior, Slack content search, file ingestion, and Enterprise Grid admin APIs are intentionally deferred.