The API and webhooks let your own systems, such as an accounting or HR system, read your payroll data from Sahora. This guide is for the person who sets up the connection, usually with your IT provider.
Before you start
- Paid plans API keys and webhooks come with the paid plans. On the Free Plan, the card shows an upgrade notice instead. See Pricing.
- Only an Owner / Management user can create keys and webhooks.
- The API reads data only. It never returns government or bank numbers.
Create an API key
- Open Company setup and scroll to API and webhooks.
- Under API keys, type a name for the key, for example Accounting system.
- Click Create key.
- Copy the key from the message right away: "Key created. Copy it now; it won't be shown again." Store it somewhere safe, such as a password manager.
The key list shows each key's name, the first characters of the key, and when it was last used.
Anyone with the key can read your company's payroll data through the API. Don't send it by chat or email. If a key may have been seen by someone else, revoke it and create a new one.
Use the key
Your system sends the key in the header Authorization: Bearer followed by the key. The read endpoints are:
| Endpoint | What it returns |
|---|---|
GET /api/v1/payroll-runs | Your payrolls with their totals (approved ones unless you ask for others) |
GET /api/v1/payroll-runs/{id}/employees | Each employee's totals and lines in one approved payroll |
GET /api/v1/employees | Your employees' master data, without government or bank numbers |
Each key may make a limited number of requests a minute. Past that, Sahora answers with status 429 and a Retry-After header saying how many seconds to wait.
Revoke a key
- Click Revoke on the key's line.
- Confirm. Systems using the key stop working at once.
Add a webhook
A webhook is an address on your system that Sahora calls when something happens. Sahora sends a signed message when a payroll is approved (event payroll_run.approved).
- Under Webhooks, type your system's address. It must start with https:// and be on the public internet.
- Click Add webhook.
- Copy the signing secret from the message: "Webhook added. Signing secret (shown once)". Give it to whoever builds the receiving side.
Each message is a JSON POST with the headers X-Sahora-Event and X-Sahora-Signature. The signature is an HMAC-SHA256 of the message body made with your signing secret, so your system can check that the message really came from Sahora.
Pause or remove a webhook
- Each webhook's line shows whether it is on or paused, and its last delivery and answer.
- Click Pause to stop sending for now, and Resume to start again.
- Click Remove to delete it.
What can go wrong
- "Give the key a name (e.g. Accounting system)." Type a name before creating the key.
- "Enter an https:// address on the public internet (not a private, local or internal address)." Use your system's public address.
- "That address could not be found. Check the web address."
- A delivery shows "error: no answer within 8 seconds" or "error: could not connect" when your system didn't answer. Sahora tries each delivery once, and redirects are not followed.
- Your system gets "Unknown or revoked API key." Check the key, or create a new one.