What are webhooks?
Receive real-time notifications from Factorial the moment an event happens, instead of polling the API.
Webhooks let your application receive real-time notifications when events occur in Factorial. Instead of repeatedly polling the API to check for changes, Factorial sends an HTTP POST request to a URL you control whenever a relevant event takes place.
This is the recommended approach for keeping external systems in sync with Factorial data — for example, triggering an onboarding workflow when a new employee is created, or updating a payroll system when contract details change.
Watch the walkthrough
A six-minute tour of everything in this section — the delivery loop, managing subscriptions, payloads, retries and troubleshooting.
For the exact structure of each payload, follow Payloads & Event Types and the callback payload documented on each webhook in the API Reference — those are the source of truth.
Why webhooks instead of polling
| Polling | Webhooks | |
|---|---|---|
| How it works | Your system calls the API on a schedule and looks for changes | Factorial calls your system when the change happens |
| Latency | As long as your polling interval | Near real time |
| Request volume | High — most calls return nothing new | One request per actual event |
| Missed changes | Possible between intervals | Delivered as they occur, with retries |
Webhooks let you build integrations that sync data between platforms, trigger downstream processes, update an external directory, or drive any workflow that should start the instant something changes in Factorial.
Technical prerequisitesWebhooks can be consumed directly by your own service, or through an intermediary automation platform (for example an iPaaS or workflow tool). Consuming them directly requires a publicly reachable HTTPS endpoint and the ability to handle incoming HTTP requests.
How the delivery loop works
- You register a webhook subscription with Factorial, providing a
target_urlthat your server exposes publicly. - When a subscribed event occurs in Factorial, a
POSTrequest is sent to your endpoint with a JSON payload describing the event. - Your server processes the payload and responds with an HTTP
2xxstatus code to acknowledge receipt.
┌────────────┐ ┌─────────────┐
│ │ 1. POST /your-endpoint │ │
│ Factorial │ ────────────────────────────────▶ │ Your server │
│ │ JSON body: the resource │ │
│ │ │ │
│ │ 2. HTTP 200 OK │ │
│ │ ◀──────────────────────────────── │ │
└────────────┘ └─────────────┘
│
│ 3. No 2xx or timeout → retry (see Webhooks Policies)
▼
Your endpoint must be publicly accessible over HTTPSFactorial cannot deliver to
localhost, private network addresses, or endpoints behind authentication that rejects our request. Plain HTTP is not supported.
Choosing your endpoint URLs
You can use the same target_url for every subscription, or a dedicated URL per event type.
Using a single URL for all events keeps your infrastructure simple, but your handler must inspect the payload to tell events apart. Using one URL per subscription type makes routing explicit and is usually easier to maintain.
Request headers
Every delivery includes standard HTTP headers plus the following Factorial-specific headers.
| Header | Always sent | Description |
|---|---|---|
x-factorial-wh-challenge | Only if a challenge was set on the subscription | Echoes the challenge value you defined when creating the subscription, so you can verify the request originates from your subscription. See Webhooks Subscriptions. |
x-factorial-author-id | No | ID of the employee or company that triggered the event. |
x-factorial-author-type | No | Either employee or company. |
The author headers are sent only when the author can be safely exposed to the subscriber. If the author is not visible to the subscriber, the headers are omitted. They are metadata only and do not change the payload body.
What's in this section
| Page | What it covers |
|---|---|
| Webhooks Subscriptions | Creating, listing, enabling, disabling and deleting subscriptions |
| Payloads & Event Types | Payload structure and the events you can subscribe to |
| Webhooks Policies | Retries, failure notifications and permissions |
| Best Practices & Troubleshooting | Building a reliable handler and diagnosing problems |
| Practical Example: Clock In a Shift | An end-to-end worked example |
Full list of available webhooksEvery subscription type Factorial supports is listed in the Webhooks section of the API Reference, together with the callback payload for each one.
Updated 9 days ago