ahlan hamad

Setup guide · Slack

Connect Slack with your own Slack app: step by step

You create the app inside your own Slack workspace, so your workspace owns it and its credentials. It takes about ten minutes and needs two people, or one person who is both: a Slack admin who may install apps, and an AhlanHamad admin with settings access. Every label below is the one you will see on screen.

Updated 20 October 2026

1. Before you start

2. In AhlanHamad: download your manifest

  1. Go to Integrations → Slack and click Start setup.
  2. Click Download manifest. The file already holds your company's three request URLs (events, interactivity and the /hamad command) and the permissions the app needs.

The request URLs are unique to your company. They only tell AhlanHamad which company a message is for — every message is still checked with your app's Signing Secret before anything happens.

3. In Slack: create the app from the manifest

  1. Open api.slack.com/apps and click Create New App.
  2. Choose From a manifest, pick your workspace, and click Next.
  3. Paste the manifest (the JSON tab), click Next, check the summary, and click Create.

Slack may say the Event Subscriptions request URL is not verified yet. That is expected: AhlanHamad can only answer Slack's check once you have connected in step 5.

4. In Slack: install the app and copy two values

  1. In the new app, open Install App and click Install to Workspace, then Allow.
  2. Open OAuth & Permissions and copy the Bot User OAuth Token. It starts with xoxb-.
  3. Open Basic Information → App Credentials and copy the Signing Secret (click Show).

You do not need the Client ID, the Client Secret or a redirect URL. The app is installed from its own settings page, so there is no sign-in redirect to set up.

5. In AhlanHamad: connect

  1. Back in Integrations → Slack, paste the Bot User OAuth Token and the Signing Secret.
  2. Click Connect my Slack app. AhlanHamad checks the token with Slack before saving it.
  3. In Slack, open Event Subscriptions. If the request URL shows as not verified, click Retry. It now shows Verified.

Slack members are then matched to employees by their verified Slack email. You can change any match in the members table on the same page.

What the app may do in your workspace

Permission (scope)Why
chat:writeSend each approver their request with Approve and Reject buttons, and update it once decided.
im:writeOpen the direct message to the approver.
commandsThe /hamad command: leave balance, approvals, leave requests, help.
users:readRead the member list to match people to employees.
users:read.emailMatch by verified email address.

No channel-reading permission is asked for. The app does not read your messages.

How your credentials are kept

6. Troubleshooting

MessageWhat to do
That is not a bot token. Copy the Bot User OAuth Token — it starts with xoxb-.You pasted another token (a user token starts with xoxp-). Copy the one under OAuth & Permissions → Bot User OAuth Token.
That is not a signing secret. Copy the Signing Secret from Basic Information → App Credentials (32 letters and numbers).Copy the Signing Secret, not the Client Secret or the Verification Token.
Slack did not accept this token. Check that the app is installed to your workspace, then copy the token again.Reinstall the app (Install App → Reinstall to Workspace) and copy the new token.
This Slack workspace is already connected to another Ahlan Hamad company.Disconnect it from the other company first, or contact us.

7. Disconnecting

  1. In AhlanHamad, click Disconnect Slack app. The token is revoked with Slack and the Signing Secret is deleted, so your request URLs stop working at once.
  2. If you no longer need the app, delete it in Slack too: Basic Information → Delete App.

Slack sources used in this guide

About AhlanHamad × Slack· All integrations