How to Configure Workspace Notifications in OrangeHRM

This article explains how to set up Workspace Notifications in OrangeHRM Starter, available starting with version 5.9. Once configured, OrangeHRM will send automated daily messages to your team's Slack channels or Google Chat Spaces for daily Birthday and Leave notifications.

Here is what those messages look like in your channel.

Birthday Notifications in Google Chat

Leave Notifications in Google Chat

Step 01: Enable Workspace Notifications

Go to Admin > Configuration > Workspace Notification Configuration and turn on the Enable toggle at the top right of the page. The change is saved immediately.

While this toggle is off, no notifications are sent regardless of how many registrations you have saved. Turning it back on resumes all active registrations.

Step 02: Get Your Webhook URL

Each notification is delivered through an incoming webhook. You need to generate a webhook URL from your chat platform before adding a registration in OrangeHRM. Follow the steps for the platform you use.

Slack

1. Go to https://api.slack.com/apps  and sign in with your Slack account.

2. Click Create New App, then select From scratch.
   
   
   

3. Enter OrangeHRM Starter as the app name, select your workspace from the dropdown, and click Create App.
   

4. On the app settings page, scroll down to Display Information and configure the following:

   • Short description - Automated birthday and leave notifications from OrangeHRM, delivered to your Slack channels.
   • App icon - Download the OrangeHRM logo from https://raw.githubusercontent.com/wiki/orangehrm/orangehrm/logos/orange.png and upload it. The icon must be a square image between 512×512 and 2000×2000 pixels.
   • Background color - #C75300
   • Click Save Changes
     
5. In the left sidebar under Features, click Incoming Webhooks and toggle Activate Incoming Webhooks on.
   

6. Scroll down and click Add New Webhook to Workspace.
   
   

7. Select the channel where OrangeHRM should post notifications and click Allow.
   

8. Copy the webhook URL that appears under Webhook URLs for Your Workspace. It will look like: https://hooks.slack.com/services/… 
   
   

9. For full instructions, refer to Slack's guide: Sending messages using incoming webhooks. 

Google Chat

1. Open the Google Chat Space you want to post to. This must be a Space, not a direct message. 

2. Click the expand arrow next to the space name at the top and select Apps & integrations. 
   

3. Click Add webhooks.
   

4. Configure the Incoming Webhook properties.

   • In the Name field, enter OrangeHRM Starter.
   • In the Avatar URL field, paste: https://raw.githubusercontent.com/wiki/orangehrm/orangehrm/logos/orange.png 
   • Click Save.
     
     
      

5. Next to the webhook entry that appears, click the vertical ellipsis (...) and select Copy link. It will look like: https://chat.googleapis.com/v1/spaces/…
   

6. For full instructions, refer to Google Chat's official guide: Build a Google Chat app as a webhook.
    

Step 03: Add a Notification Registration

On the Workspace Notification Configuration page, navigate to the Notification Registration section and complete the relevant details in the form.

Click + Add Registration to save. A green confirmation message will appear if the registration was saved. A red error message will appear if the webhook URL is invalid or unreachable.

Step 04: Test the Connection

Before relying on a registration for daily use, send a test message to confirm the webhook is working.

Click the Send Test button inside the registration form or use the Send Test button in the notifications registration table.

A clearly labelled test message will be posted to the configured channel immediately. The test does not apply the subunit filter and does not require the Enable toggle or the registration's Active switch to be on.

Test Notification: Birthday Notifications in Google Chat

Test Notification: Leave Notifications in Google Chat

If the test message does not arrive, check that the webhook URL is correct and that the channel still exists in your chat platform.

Step 05: Manage Your Registrations

All saved registrations appear in a table below the form.

Edit	Click Edit on any row to update the subunit, webhook URL, channel label, timezone, or send time.
Active toggle	Temporarily turn a registration off without deleting it. Inactive registrations are skipped until re-enabled.

If you change a registration from one platform to another, you will be asked to enter a new webhook URL. The previously saved URL cannot be carried over.

Scheduling (for IT administrators)

OrangeHRM's built-in scheduler triggers notifications. The following command must be scheduled to run every five minutes on the server where OrangeHRM Starter is hosted:

php bin/console orangehrm:run-schedule

Each registration fires once per day at its configured send time and timezone. Running the command more frequently than every five minutes is safe. 

If a notification for a given registration has already been sent today, subsequent runs skip it. Every delivery attempt is recorded in a database log retained for 30 days, which can be used to confirm what was sent and when.

If this command is not scheduled on the server, no notifications will be sent regardless of how the registrations are configured. The file paths used in the examples below are for illustration only. Your IT administrator should replace them with the actual OrangeHRM installation path on your server.

Linux (cron)

The cron job should run as the web server user (typically www-data on Debian/Ubuntu or apache on RHEL/CentOS) to ensure PHP has the correct permissions to access OrangeHRM files.

1. Open the crontab for the web server user:
   sudo crontab -u www-data -e
2. Add the following line at the bottom, replacing the path with your OrangeHRM installation directory.
   */5 * * * * cd /var/www/orangehrm && php bin/console orangehrm:run-schedule
3. Save and exit. Verify the entry was saved:
   sudo crontab -u www-data -l

Windows (Task Scheduler)

These steps must be performed on the server where OrangeHRM Starter is hosted, not on a local machine.

1. Via command prompt (run as Administrator)
   • Replace the path with your OrangeHRM installation directory before running this command.
     schtasks /create /tn "OrangeHRM Scheduler" /tr "php C:\path\to\orangehrm\bin\console orangehrm:run-schedule" /sc MINUTE /mo 5
      
2. Via the GUI:
   1. Press Win + R, type taskschd.msc, and hit Enter.
   2. Click Create Task in the right panel. 
      Note: Use Create Task, not Create Basic Task. Basic Task does not support sub-hourly repeat intervals.
   3. On the General tab, give the task a name such as OrangeHRM Scheduler.
   4. Go to the Triggers tab, click New, and set Begin the task to On a schedule.
   5. Select one time and set a start time. Then check Repeat task every, set it to 5 minutes, and set the duration to Indefinitely.
   6. Go to the Actions tab, click New, and set Action to Start a program.
   7. In the Program/script field, enter php. In Add arguments, enter the full path to the OrangeHRM console on your server, for example: C:\path\to\orangehrm\bin\console orangehrm:run-schedule
   8. Click OK to save.

Notes and limitations

• Leave Today includes only employees with a leave status of Approved or Taken. Pending, rejected, and cancelled leave is excluded.

• Terminated employees are excluded from all notifications.

• Employees with no subunit assigned appear only in registrations where the Subunit field is left blank.

• Messages are sent in English in this feature.

• This is a one-way daily broadcast. Real-time alerts and inbound chat queries are not supported.

• The integration does not support automated user provisioning.
   

FAQs

What do the notification messages look like?

Birthday messages include each employee's name and department, along with a short celebratory note. Leave Today messages include each employee's name, leave type, and department.

Eg: Birthday Notifications in Google Chat

Eg: Leave Notifications in Google Chat

If no employees match the criteria on a given day (no birthdays, or no one on approved or taken leave), no message is sent for that registration.

Why wasn't the notification sent today?

Check the following in order:

1. The Enable toggle at the top of the Workspace Notification Configuration page is on.
2. The registration's Active switch is on.
3. The Send Time and Timezone on the registration match the time you expected the message to arrive.
4. Your IT administrator has confirmed the OrangeHRM scheduler is running. Notifications will not send if the scheduler command is not active on the server. See Scheduling above.
5. The webhook URL is still valid. Webhook URLs can be revoked by the chat platform if the app is uninstalled or the channel is deleted. Use Send Test to verify the connection.

Why is an employee not appearing in a notification?

There are a few reasons an employee may be excluded:

1. Their employment status is set to Terminated in OrangeHRM.
2. The registration is scoped to a Sub Unit they do not belong to, or they have no Sub Unit assigned, and the Sub Unit field is not blank.
3. For Leave Today: 
   • Employee’s leave request exists, but its status is Pending, Rejected, or Cancelled. Only Approved and Taken leaves are included.
   • The employee’s leave was added after the notification for that day had already been sent. Each registration fires once per day at the configured send time.
4. For Birthday: 
   • The employee’s date of birth is not entered in their OrangeHRM employee profile. If this field is blank, they will not appear in any birthday notifications.
   • The employee’s birthday falls on today's date in a different timezone than the one configured on the registration.

How do I notify different departments on separate channels?

Create one registration per department and select a different Subunit for each. Point each registration to its own webhook URL. 

For example, a Leave Today registration for an Engineering posting to one channel and a separate one for a Marketing posting to another. To notify all employees in one channel, leave the Subunit field blank.

Can I send the same notification to multiple channels?

Yes. Create a separate registration for each channel. You can have as many registrations as you need. 

For example, one all-company Birthday registration posting to a general channel, plus individual Leave Today registrations for each department posting to their own channels.

What is a duplicate registration warning?

When saving a new registration, OrangeHRM checks whether it overlaps with an existing one for the same event type and webhook URL. A warning appears if an overlap is detected. 

For example, if you have an all-employees Leave registration for today and then add a department-specific one that points to the same webhook URL, some employees would receive the same message twice. 

The warning does not block you from saving. You can go back and adjust, or save anyway if the duplication is intentional.