Slack app setup
Create the Dibbla Slack app from a version-stamped manifest, prove the registration works with preflight and a troubleshooting matrix, then install it into your workspace — and know what a disconnect does and does not take with it.
Dibbla can deliver personal notifications into your Slack workspace through a real Slack app: a bot that posts, and a per-user identity link so the right person gets the right message. This page is for whoever creates and verifies that app — a Dibbla operator, or an admin of a self-hosted installation.
It is deliberately a setup and verification guide, not just setup. A Slack app registration that saves is not one that works: saving proves five fields passed a validator, not that Slack can reach your installation, that the redirect address matches the route your Dibbla version actually serves, or that the signing secret in the box is the one Slack signs with. Every one of those fails the same way — later, inside Slack, with an error that names neither side. So the last third of this page is about proving it before anyone installs anything.
Scopes and callback addresses are pinned to a contract version, shown on the Slack app card in your Dibbla console and stamped into the manifest you generate. If your console shows a different version than the one at the top of this page, read the upgrade section before following the steps.
Before you start
- You need to be an owner or admin of your Dibbla organization.
- You need permission to create an app in the Slack workspace’s developer area. Some workspaces require an admin to approve new apps — find that out first, not after you have created it.
- Your Dibbla installation needs a public HTTPS origin. Slack calls back from
its own servers, so
localhost, a private IP or a.localname can never work — not even for testing. If you are trying this on a laptop, use a tunnel and register the tunnel’s public URL. - Managed Dibbla customers: there is nothing to do here. The Slack app is operated by Dibbla, your console will say so, and the configuration form is not shown. This page is for self-hosted installations and for Dibbla operators.
Never point one Slack app at both a production and a development Dibbla. Slack matches redirect addresses exactly, and an app that carries both environments’ callbacks is one mistake away from sending production authorization codes to a test host. Create a second app, with its own name, for each environment you run. Dibbla’s preflight refuses a development-looking address on a production deployment for this reason.
The four addresses, and why there is only one to type
Everything Slack needs to call is derived from a single value — your installation’s public origin. You type the origin; Dibbla derives the rest, and a Dibbla upgrade that moves a route updates every environment at once.
| What Slack calls it | Address |
|---|---|
| Redirect URL (workspace install) | <your origin>/api/notify/slack/callback |
| Redirect URL (Sign in with Slack) | <your origin>/api/notify/slack/signin/callback |
| Request URL (Event Subscriptions) | <your origin>/api/notify/slack/events |
For a self-hosted installation the origin is your console’s, for example
https://console.example.com. Open Organization settings → Integrations →
Dibbla Slack app → Show setup values and Dibbla will print the exact strings
for your installation, with a copy button on each.
Slack arrives with no Dibbla session. If your gateway or reverse proxy puts
/api/notify/slack/ behind authentication, Slack receives a redirect to a
login page and the install fails with an error that mentions neither
authentication nor your proxy. Dibbla’s own chart routes this prefix publicly
by default; if you front Dibbla with something else, allow it there too. The
routes are safe to expose — each one proves its own caller (Slack’s request
signature on the events endpoint, a one-time state on the callbacks).
Two flows, two scope sets — do not merge them
This is the part that costs people an afternoon, so it is worth thirty seconds now. Installing the app into a workspace and signing a person in with Slack are different OAuth flows against different Slack endpoints, and their scopes are not interchangeable.
| Workspace install | Sign in with Slack | |
|---|---|---|
| What it does | Gives Dibbla a bot that can deliver messages | Binds one Dibbla user to one Slack user |
| Who does it | An organization admin, once | Each user, for themselves |
| Slack endpoint | slack.com/oauth/v2/authorize | slack.com/openid/connect/authorize |
| Scopes | Bot scopes (below) | openid, email, profile |
| Redirect | /api/notify/slack/callback | /api/notify/slack/signin/callback |
Sign in with Slack is the OpenID Connect flow. Slack also has an older family
of user scopes named identity.something. They do the same job and Slack will
refuse a request that asks for both — the authorize call fails outright
rather than degrading. If you paste scopes from an older tutorial and end up with
both, this is what has happened. Use the manifest below and the question does not
arise.
Bot scopes Dibbla asks for
| Scope | Why Dibbla needs it |
|---|---|
chat:write | Post the notification |
im:write | Open the direct message to post it into |
team:read | Read the workspace ID — what binds an installation to one Dibbla organization |
users:read | Resolve a Slack user to a member of the workspace |
users:read.email | Match a Dibbla account to a Slack account by email |
Nothing that can read conversation content, and nothing that acts on a user’s behalf. If your security review asks, that is the list — and it is enforced by a test in Dibbla’s source, not by this page.
Create the app
-
Generate the manifest from your own installation
In Dibbla, open Organization settings → Integrations → Dibbla Slack app and choose Show setup values. Enter your installation’s public origin and choose Render.
You get a JSON app manifest with your addresses already filled in and the contract version stamped into the app’s description. Copy it.
Generating the manifest does not require a saved registration — that is deliberate, because the app you are about to create is what produces the client ID you will paste back into Dibbla.
-
Create the Slack app from that manifest
Go to Slack’s Your Apps page and choose Create New App → From a manifest, pick the workspace you will develop it in, and paste the JSON.
Review the summary Slack shows you: the permissions, the two redirect URLs and the request URL should match the table above. A manifest is reviewable in a way a sequence of screenshots is not — this is the step where a wrong origin is cheap to notice.
Slack will try to verify the Request URL for event subscriptions right away by sending a signed challenge. It will fail at this point, and that is expected: Dibbla does not yet have your signing secret. You will come back and retry it in step 5.
-
Copy the three values back into Dibbla
On the app’s Basic Information page, under App Credentials, you need:
- Client ID — not a secret, but Dibbla only ever shows it back masked.
- Client Secret — choose Show, copy it once.
- Signing Secret — this is the one Slack signs inbound callbacks with. It is a different value from the client secret and pasting one into the other’s box is the single most common setup mistake.
In Dibbla, choose Configure on the Slack app card, paste all three, enter your base URL and the install redirect URL, and save.
Dibbla stores both secrets encrypted and never shows them again — not in the interface, not through the API, not in logs. If you lose one, generate a new one in Slack and save it again; that is a rotation, not a reinstall.
-
Run preflight
Choose Run preflight on the same card. This needs no Slack credentials and no installation — it checks what you have saved, and it goes out to the public internet and back to prove Slack could reach you.
Work down any red rows using the troubleshooting matrix. Each row names the one thing to change. Do not continue until preflight is green.
-
Let Slack verify the request URL
Back in Slack, open Event Subscriptions and retry the Request URL. Slack sends a signed challenge; Dibbla verifies the signature against the signing secret you saved and answers it. Slack shows Verified.
Run preflight once more. Below the checks it now reports the last Slack callback this installation saw — which answers the question you actually have: did the thing I just clicked in Slack arrive here? If Slack says “Verified” and Dibbla reports an accepted callback, the signing secret is correct.
-
Install the app into your workspace
In Dibbla, under Slack workspace, choose Install in Slack. Dibbla mints a single-use, CSRF-protected state, sends you to Slack’s consent screen, and Slack returns you to this page with the result. There is no bot token to copy: Dibbla receives it from Slack directly, stores it encrypted, and never shows it again — not even masked.
The panel then reports the workspace name and ID, who installed it, the scopes the workspace actually granted, and when Dibbla last verified the connection. Verify connection asks Slack again at any time.
A workspace belongs to one Dibbla organization and an organization to one workspace. Installing into a second workspace is refused rather than silently moving your notifications; disconnect first if you mean to change.
-
Optional: post a test message
Test connection is separate from the install and needs a bot token you paste yourself, from the Slack app’s OAuth & Permissions page. It is for diagnosing a token you hold, not for connecting a workspace — the install above is what produces a workspace connection.
Choosing to send a test message posts one clearly labelled message and nothing else: no subscription is created and no Dibbla event is recorded, so a test leaves nothing behind for someone to unsubscribe from later.
The bot token you paste here is sent to Slack for the test and dropped. Dibbla does not store it.
Disconnecting, and what survives it
Disconnect revokes Dibbla’s token at Slack and stops every Slack delivery for the organization. It does not touch anyone’s notification preferences: subscriptions are left exactly as they are, so reconnecting resumes them with nothing to re-choose.
The same is true when the disconnection happens on Slack’s side. If someone removes the app from the workspace, or Slack revokes the token, Dibbla is told on the events endpoint you verified above, moves the workspace to Disconnected, and stops delivering — again without discarding a preference.
Replacing the client ID on the registration above is a different thing from rotating its secret. A rotation keeps the installation; a new client ID is a different Slack app, so the stored token is dropped and the workspace must be installed again.
Verify: what each check proves
Preflight and the connection test are separated by what they need. Preflight needs only your saved registration and can be run before Slack is involved at all; the connection test needs a bot token you paste, which only exists after an install. Neither is the install: Install in Slack is what creates the workspace connection Dibbla delivers through.
Preflight
| Check | What a pass proves |
|---|---|
scope_contract | The scope sets in this Dibbla build are internally consistent — install and sign-in scopes are disjoint, and the user set is OpenID Connect only |
credential_storage | This deployment has an encryption key, so secrets could be stored sealed rather than refused |
registration | A complete registration exists: client ID, client secret and signing secret |
urls | Both addresses are absolute HTTPS on the same origin |
environment | The callback address can actually receive an inbound call, and is not a development address on a production deployment |
redirect_contract | The redirect you saved is the exact route this Dibbla version serves |
signin_callback | Reminds you to register the second redirect URL, which the install flow does not need and the sign-in flow cannot work without |
public_reachability | A request left this installation, travelled the public internet to your callback address, and came back to this installation — not to a parked domain, a proxy or a different Dibbla |
events_reachability | The same, for the events request URL |
signature_verification | The stored signing secret is a usable key: a genuine callback verifies, a forged one is refused, and a replay older than five minutes is refused |
Connection test
| Check | What a pass proves |
|---|---|
bot_token | The token is a bot token (xoxb-), not a user token |
slack_api | Dibbla can make an outbound HTTPS connection to Slack |
bot_auth | Slack accepts the token and reports which workspace it belongs to |
workspace_match | That workspace is the one you expected — the failure that is hardest to see from inside Slack |
bot_scopes | The installation actually granted every scope this version needs |
test_message | A marked test message reached a destination you chose explicitly, without creating a subscription or an event |
Troubleshooting matrix
Keyed on the check ID shown next to each row in the console.
| Check | Symptom | Cause | Fix |
|---|---|---|---|
registration | ”No complete registration is stored” | One of the three credentials is missing | Re-save all three. An incomplete registration is reported as absent rather than as partly working |
urls | ”Redirect URL is on a different origin” | The redirect points somewhere other than your installation | Both must be your own origin. A redirect elsewhere would send Slack authorization codes to a host Dibbla does not control |
environment | ”not reachable from the public internet” | localhost, a private IP, or a .local name | Slack dials from its own servers. Publish on a public hostname, or use a tunnel and register the tunnel’s URL |
environment | ”looks like a development address” on production | Production Dibbla configured with a development host | Use the production console’s hostname, and a separate Slack app for development |
redirect_contract | Slack says “redirect_uri did not match” | The redirect in Dibbla and the one in Slack differ, or neither is the route this version serves | Copy the address Dibbla prints into both places, character for character |
public_reachability | ”Could not reach…” | DNS does not resolve, or the TLS certificate is not valid from outside | Check DNS and the certificate from a machine outside your network |
public_reachability | Answered 404 | The hostname answers, but not with this Dibbla — or the gateway does not route the Slack prefix publicly | Route /api/notify/slack/ as a public prefix |
public_reachability | ”the route is behind authentication” | The Slack prefix sits behind your login | Move it to the public routes. Slack has no Dibbla session |
public_reachability | ”answered 200 but did not echo the probe” | The hostname is served by something else | A parked domain, a proxy, or a different Dibbla installation. Point the base URL at this one |
signature_verification | ”could not be decrypted” | The encryption key that sealed it has been retired | Re-save the signing secret, or restore the key and run the re-key sweep |
| — | Slack will not verify the Request URL | Signing secret missing or wrong; or the clock is wrong | Re-copy the Signing secret (not the client secret). If preflight is green and Slack still fails, check NTP — a clock more than five minutes out rejects every genuine callback |
bot_token | ”is a user token, not a bot token” | The User OAuth Token was copied | Use the Bot User OAuth Token. Dibbla posts as the app, never as a person |
slack_api | ”Could not reach slack.com” | No outbound path from the Dibbla host | Allow egress to slack.com:443, or configure a proxy |
bot_auth | invalid_auth | The token was invalidated, usually by a reinstall | Copy the current token from OAuth & Permissions |
bot_auth | token_revoked / account_inactive | The app was removed from the workspace | Install it again and use the new token |
workspace_match | ”belongs to workspace … but … was expected” | The token came from a different workspace | Install into the intended workspace and use that installation’s token |
bot_scopes | ”Missing bot scopes” | A scope was added in Slack but the app was not reinstalled | Adding a scope does not change an existing token. Reinstall, then test with the new token |
test_message | not_in_channel | The app is not a member of the channel | Invite it in the channel, then test again |
test_message | channel_not_found | Wrong ID, or the ID belongs to another workspace | Copy the ID from Slack’s channel details |
Rotating a secret
Rotating a secret and replacing the app are different operations with different consequences, and Dibbla treats them differently on purpose.
Rotating the client secret or the signing secret — same app, new credential. Generate the new value in Slack, save it in Dibbla, leave the client ID unchanged. Existing workspace installations and their bot tokens keep working; nobody has to reinstall anything. That is the whole point: a leaked secret must be replaceable in a minute, not over a change window.
Leave a secret field blank when saving to keep the stored value. You can change a callback URL without re-typing credentials you were never shown.
Replacing the app — a different client ID. Dibbla treats this as what it is: everything installed under the old app is invalid. In the same transaction as the write, Dibbla disables the organization’s Slack integration and its Slack subscriptions, and tells you how many. The workspace must install the new app before notifications resume.
Removing the registration does the same, and is the clean way to disconnect Slack entirely.
Upgrading between contract versions
A Dibbla release that changes a scope or a callback address bumps the contract version. When your console shows a version newer than the app you created:
-
Re-generate the manifest
From the same card. Compare it against your Slack app’s current configuration — the differences are the work.
-
Apply the differences in Slack
Slack’s App Manifest page accepts an edited manifest directly. Changing a redirect URL or an event subscription takes effect immediately.
-
Reinstall if scopes changed
A scope added in Slack is not on tokens that already exist. If the upgrade added a bot scope, the workspace must reinstall the app, and the bot token changes.
-
Re-run preflight and the connection test
Preflight confirms the addresses; the connection test confirms the new token carries the new scopes.
Version history
| Contract | Dibbla release | Change |
|---|---|---|
| 1 | current | First version. Bot scopes chat:write, im:write, team:read, users:read, users:read.email; user scopes openid, email, profile; callbacks under /api/notify/slack/ |
What this page does not cover
Installing the app into a workspace as an everyday admin action, linking your own Slack identity, choosing which apps you get notified about, and the notifications themselves are separate — see Notifications. Slack Marketplace distribution, buttons that change things from inside Slack, and Microsoft Teams are not part of this contract.