Webhooks

What is a webhook in Simployer One?

A webhook is a message Simployer One sends automatically to a URL you control whenever an employee event happens. Instead of your system repeatedly asking Simployer One "has anything changed?", Simployer One notifies your endpoint as soon as a change occurs.

Important: Requires owner permission. Only account owners can see and manage webhooks.

Webhooks currently cover employee events only. A webhook tells you that something changed — it does not include the full current record.

How do I set up a webhook in Simployer One?

1. Go to Settings > Integrations.
2. Select Add webhook.
3. Fill in the webhook details:
   • Name – a label so you can recognize this webhook.
   • URL – your endpoint. It must be publicly reachable and start with https://.
   • Secret key (optional) – a signing secret of at least 32 characters. If set, every delivery is signed so your endpoint can verify it came from Simployer One. Only a masked hint (the last 4 characters) is shown after saving. A change takes effect immediately, so update your endpoint at the same time to keep verification working.
   • Custom headers (optional) – extra headers sent with every delivery, for example a token or routing header your endpoint expects (such as X-Api-Key). Header names starting with X-Simployer- are reserved.
4. Select Add Webhook to save.

Expected result: The webhook is active immediately and receives all employee events — there's no per-event selection.

What events trigger a webhook in Simployer One?

Once a webhook is set up, Simployer One sends every employee event to your endpoint as it happens. You can't select individual event types — a webhook receives all of them.

Tip: Use Created to know as soon as an employee record exists (some details may still be missing at that point). Use Onboarded to wait until the employee has been invited and their setup is complete, for example before provisioning downstream accounts. Updated then tells you about later changes to that employee.

How reliable is webhook delivery in Simployer One?

• A delivery succeeds when your endpoint returns a 2xx response. Acknowledge quickly and do any heavy processing afterward.
• Failed deliveries are not retried automatically. If your endpoint is unavailable or returns a non-2xx response, the delivery is marked failed and is not resent, so you can miss an event.
• Delivery order isn't guaranteed, and the same event may occasionally arrive more than once (delivery is at-least-once, not the result of retries). Each event carries a unique ID and a timestamp — use them to order changes and skip duplicates you've already processed.
• Review delivery attempts and outcomes in the webhook's delivery log. Log entries are retained for a limited period and then removed automatically.

Important: Because failed deliveries aren't retried, monitor the delivery log and reconcile any missed events by fetching the current record from the HRM One API.

How are webhook deliveries secured in Simployer One?

• HTTPS only. Deliveries are always sent over HTTPS.
• Validate input. Treat every payload as untrusted input and validate it before acting on it.
• Optional signing. If you set a secret key on the webhook, every delivery is signed so your endpoint can confirm it came from Simployer One. With no secret set, deliveries are sent unsigned. The exact signature format and verification steps are in the HRM One API reference.

Why doesn't my webhook signature verify?

The most common cause is a secret key mismatch: if you changed the secret in Simployer One but your endpoint is still using the old one (or vice versa), every delivery will fail to verify. Update both to the same value.

Other causes include computing the HMAC over a re-serialized copy of the payload instead of the raw body as received, or not appending ":" + X-Simployer-Timestamp before hashing (see the API reference for the exact steps).

If none of these apply, treat the delivery as untrusted and don't process it — a mismatch can also mean the request didn't genuinely come from Simployer One, or the body was altered in transit.

How do I test a webhook in Simployer One?

Use Send test event on a webhook to deliver a sample payload to your URL, so you can confirm your endpoint receives and accepts deliveries before relying on live events. The test uses synthetic data (a fictional "Test User"), not a real employee record.

How do I edit or delete a webhook in Simployer One?

• Edit settings: From the webhook's actions menu (⋯), choose Settings to change the name, URL, secret key, or custom headers. Changes take effect immediately.
• Delete: From the same actions menu (⋯), choose Delete to stop receiving events. Deletion is immediate.

FAQs

Can I choose which events I receive?

Not currently. A webhook receives all employee events; there's no per-event selection.

What happens if my endpoint is down?

The delivery is marked failed and isn't retried. Monitor the delivery log and reconcile missed events using the HRM One API.

How do I stop receiving events?

Open the webhook's actions menu (⋯) and choose Delete.