Your developers, or a supplier you work with, can connect other systems to KalHR: an accounting package that picks up each payroll, an identity system that creates accounts for new starters, a rota tool that knows who is on leave. They need two things from you:
- An API key, so their system can read from KalHR.
- A webhook endpoint, so KalHR can tell their system when something happens.
This page covers what you do in KalHR. Everything a developer needs (code samples, every endpoint and event) is in KalHR Developers.
Who can set them up
Four permissions control integrations. Administrators have them; give them to anyone else on their role in Users & roles.
| Permission | Lets a person |
|---|---|
| View API Keys | See the organisation's keys (never the keys themselves), what they can reach, and when they were last used |
| Manage API Keys | Create, change and revoke keys |
| View Webhooks | See webhook endpoints and their delivery log |
| Manage Webhooks | Add, change and remove endpoints, rotate their secrets, send test events and redeliver |
Integrations are part of the Premium and Enterprise plans, and open to every organisation while the free usage policy lasts.
Create an API key
- Open Settings → API keys and select Create key.
- Name it after the system that will use it, such as Accounting system.
- Under Access, choose View for each module the system needs to read, and leave the rest at No Access. Ask the developer what they need; a system that reads leave doesn't need payroll.
- For a short project or a contractor, choose an Expires date.
- Select Create key, then send the key to the developer through a secure channel: a password manager's sharing feature, not email or chat. It is shown only once.
A key can never be given more access than you have yourself, and it can never pay salaries or loans, or manage users, roles, keys or webhooks.
The keys page shows when each key was last used. Changes made with a key appear in the audit log (More → Access Management → Audit log) under its name, such as API: Accounting system.
Revoke a key when the system no longer needs it, or straight away if it may have leaked. Anything using it is refused within a minute.
Add a webhook endpoint
The developer gives you a URL starting with https://.
- Open Settings → Webhooks and select Add endpoint.
- Paste the Endpoint URL and add a description.
- Choose Every event, or Selected events and tick the ones the developer asked for.
- Select Add endpoint, and send the signing secret to the developer the same secure way as a key. It is shown only once.
- Select Test on the endpoint. The Delivery log shows within seconds whether their system answered.
If an endpoint keeps failing, KalHR switches it off and emails your administrators. Once the developer has fixed their system, switch it back on and use Redeliver in the delivery log for anything that was missed.
Related
- KalHR Developers: for the people building the integration
- Security checklist
