This article covers the Integrations section of the Company Settings screen. It has two parts: API key cards for ready-made integrations at the top, and Webhooks (Outbound Notifications) below. Users with the View Company Settings permission can see the webhook list; adding, editing, deleting, testing and retrying webhooks requires the Company Permission Settings permission.

Before you start

You need the Company Permission Settings permission (Manage Permissions).
For a webhook, have the address of the system that will receive the events (a target URL starting with https).
The Agentic Payroll key requires the Payroll Manager Permission.

Step by step

In the left menu, go to Configuration > Company settings.
In the settings menu on the left, click Integrations under the Modules & Display group.

Getting an API key for a ready-made integration

The section has Hirex and Agentic Payroll cards.

On the card you want to connect, click Get API Key. The key is created and shown in a window.
Click the copy icon in the window and paste the key into the other system's integration screen. The Agentic Payroll key also identifies the company it belongs to, so you do not need to enter company details separately.
To see the key again later, click View API Key on the card.

Note: Because the Agentic Payroll key gives access to the company's payroll data, only users with the Payroll Manager Permission can create it. When you create a new key, the key you previously created for the same integration is deleted.

API keys for PDKS devices and external access systems are not managed here but in the PDKS module settings (PDKS overview).

Defining a webhook

A webhook sends an instant request to an address you choose when an event happens in Teamso. Supported events:

Event	When it is sent
Employee Hired	When an employee is hired
Employee Terminated	When an employee's termination is recorded
Termination Cancelled	When a termination is cancelled
Organization Change	When an employee's organization details change
Badge awarded	When an award becomes active: a badge without approval is given, an award waiting for approval is approved, or an automatic rule gives a badge

In Webhooks (Outbound Notifications), click Add Webhook. The New Webhook window opens.
Fill in Name, Target URL and Events. All three are required. The target URL must start with http:// or https:// (e.g. https://example.com/webhooks/teamso); an address like www.example.com is not accepted.
Make sure the Active switch is on.
If the target system does not accept the standard Teamso format, turn on Advanced: customize the request format. Here you can set the Method, Body format (form fields or JSON), Parameters and, under Advanced settings, custom headers and a Failure marker. Use the Insert variable menu to put employee data into values, and Preview to see the request built with sample employee data (the preview does not send anything; when Badge awarded is the only selected event, sample badge data is used). This option is meant for developers.
Variables are written inside double curly braces; filters are chained with a vertical bar and applied left to right: {{ variable | filter | filter }}.
- trim: Removes leading and trailing spaces
- lower / upper: Lowercase / uppercase (Turkish rules)
- ascii: Simplifies Turkish characters (ş → s, ı → i)
- initial: First letter only
- first / last: First / last word; after split, the first / last part
- nospace: Removes all spaces
- alnum: Removes everything except letters and digits
- date: Date part only (yyyy-MM-dd)
- split:'separator': Splits the text at the quoted separator
Examples: {{ email | split:'@' | first | lower }} gives the part of the email before the @ ([email protected] → ayse.yilmaz); it is also under Insert variable > Ready-made expressions as Username (part of the email before @). {{firstName|initial|lower|ascii}}{{lastName|nospace|lower|ascii}} builds a username from the first initial and the last name (Ayşe Yılmaz → ayilmaz).
The Organization Change event (position, department, manager, branch or custom field change) always carries the employee's whole organization data: {{branch}}, {{department}}, {{position}} and {{manager}} hold the current values, and in the old…/new… pairs an unchanged field has the same old and new value. You can therefore write every field to the target system on each event; an unchanged field is never sent empty. A change of the manager alone also sends the event.
Click Save.

When you save a new webhook, the Webhook Secret window opens. This secret is shown only once; copy it and store it securely. Every request body is signed with this key using HMAC-SHA256 and the signature is sent in the X-Teamso-Signature header, so the receiving system can verify that the request came from Teamso.

Badge awarded event

The Badge awarded event is sent when an award becomes active in the Performance module. No event is sent for an award that waits for approval, is rejected or is revoked. When one badge is given to several people at once, each person gets a separate event.

People appear only by id (userId, awardedById) and display name (fullName, awardedBy); the recipient's branch, department and position names are included as well. E-mail, name parts, national ID number, phone and custom fields are never sent. For an award visible only to the person and their manager ("visibility": "PRIVATE") the message is not sent (message is empty). Points are sent only when the company shows points.

Field	Meaning
`badgeName`, `badgeCategory`, `badgeTier`	Name, category and tier of the badge
`fullName`, `branch`, `department`, `position`	The person who got the badge
`awardedBy`	The person who gave it; empty for an automatic rule
`source`	Source: `MANUAL` (HR or badge admin), `MANAGER`, `PEER` (colleague), `RULE` (automatic rule), `INTEGRATION` (external system)
`sourceRef`	The event id an external system sent (`INTEGRATION:...`) or the goal period (`GOAL_PERIOD:...`)
`visibility`, `message`	`PUBLIC` or `PRIVATE`; the message only for `PUBLIC` awards
`awardedAt`	When the award became active (Turkey time)
`silent`	`true`: the badge was given when an automatic rule was run with Apply to the past and notifications off; the event is sent for your records, not to be announced

In the custom request format these fields are in the Badge group of the Insert variable menu and are used as variables such as {{badgeName}}.

Sharing on Slack or Microsoft Teams: Teamso does not post awards to Slack or Teams itself. Connect the webhook to your own automation tool (e.g. Make, Zapier, n8n or Power Automate) and forward it to your channel from there:

Create a webhook trigger in your automation tool and enter its address as the Target URL in Teamso; select Badge awarded under Events.
Add a filter to the flow: only events whose data.visibility is PUBLIC and data.silent is false continue. Awards visible only to the person and their manager, and badges given by Apply to the past with notifications off, then never reach the channel.
In the Slack or Teams step, build the message from the event fields, e.g. {{data.fullName}} was recognised by {{data.awardedBy}} with the "{{data.badgeName}}" badge: {{data.message}}.

Teamso's custom request format can send a request straight to a Slack or Teams address, but it cannot filter events: awards visible only to the person and their manager would reach the channel too. Use an automation tool that can filter for channel posts.

Testing and monitoring deliveries

From the action menu on a webhook row you can:

Send Test: sends a request with sample data to the target and shows the result (HTTP code). For a custom request format you are first asked to confirm that A real request will be sent; the target system may process it (e.g. create a test user).
Delivery Log: lists the Event, Status (Successful, Failed, Pending), HTTP Code, Attempts and Date of sent requests. Use Retry to re-queue a failed delivery. For a long list, use the paging at the bottom of the window; when there are no deliveries yet, the window only shows the "No deliveries yet." note.
Edit and Delete: no more notifications are sent to a deleted webhook's address.

Result

Active webhooks automatically send a request to the target address when the selected events happen. You follow the results in the Delivery Log.

Common problems

Symptom: Saving shows "Name, target URL and at least one event are required."
Cause: One of the required fields is empty.
Solution: Fill in all three fields and save again.

Symptom: Saving shows "The target URL must start with http:// or https://".
Cause: The address is incomplete or mistyped, such as www.example.com or http//:example.com.
Solution: Write the full address starting with https:// (e.g. https://example.com/webhooks/teamso).

Symptom: Saving shows "Template error ... Unknown filter".
Cause: The template uses a filter that is not in the list, or a wrongly written argument (e.g. split without a separator or without quotes).
Solution: Use the filter names in the table above and put the split separator in quotes: split:'@'.

Symptom: Deliveries are shown as Failed in the delivery log.
Cause: The target system returns an error code, cannot be reached, or its response body contains the Failure marker text.
Solution: Check the response in the row details, fix the target system and click Retry.

Symptom: There is no Add Webhook button, the row menu only offers Delivery Log, the Active switch is locked and the section says "You can view this setting, but you do not have permission to edit it."
Cause: You have the View Company Settings permission but not Company Permission Settings. You can see the webhooks and their deliveries, but not add, edit, delete, test or retry them.
Solution: Ask a company administrator for the Company Permission Settings permission (Manage Permissions).

Symptom: I lost the webhook secret.
Cause: The secret is shown only when the webhook is created.
Solution: Delete the webhook, create it again and enter the new secret in the receiving system.

Symptom: The Agentic Payroll card shows "A payroll manager can get the API key." instead of Get API Key.
Cause: You do not have the Payroll Manager Permission; the button is shown only to users who have it.
Solution: Get the permission in the payroll module and try again (Manage Permissions).

Integrations and webhooks (API keys, outbound notifications)