Webhooks Policies

Notifications and retries

To let your service recover from temporary errors, Factorial retries failed deliveries automatically.

A delivery is considered failed when your endpoint does not return a 2xx status code, or does not respond within the timeout window.


Maximum attempts	20
Retry window	48 hours from the event
Email alerts on	Retry #1, #5, #10 and every attempt after that
After the window	Final email sent and the subscription is disabled

❗️
Exhausted retries disable the subscription
Once the maximum number of retries or the 48-hour window is reached, you receive a final email notification and the subscription is disabled — no further events are delivered.
This is not a silent failure, but it does require action on your side. Once your service is healthy again, re-enable the same subscription as described in Enabling or disabling a subscription. You do not need to create it from scratch.

Because deliveries are retried, your endpoint may receive the same event more than once. Payloads do not carry a unique per-delivery identifier, so your handler must be idempotent by design — see Make your handler idempotent.

Email recipient resolution

Failure and disabling notifications are sent to the first available contact in this order:

Partner email — from the marketplace integration linked to the OAuth application.
Technical support contact — the email configured by the company in Settings → API Notifications (see below).
OAuth application owner — the user who owns the OAuth application that created the subscription.
Subscription author — the user who originally created the webhook subscription.
Company admins — if none of the above can be resolved, all company administrators with login rights are notified.

If no recipient can be resolved at all, the notification is skipped and the event is logged internally.

Configuring the technical support contact

Companies can define a dedicated address that receives API notifications — webhook failures and automatic disabling events — so alerts reach the team responsible for the integration rather than an individual's inbox.

Go to Settings (for example https://app.factorialhr.com/settings/).
Open the API Notifications section.
Enter the address that should receive API notifications in the Technical support contact field.
Save the changes.

Once saved, this address takes precedence over the OAuth application owner and the subscription author, and is only superseded by the partner email of a linked marketplace integration.

📘
Recommended for production integrations
Setting a technical support contact is the most reliable way to make sure webhook failures are seen. Without it, alerts may land with whoever happened to create the subscription.

Webhook permissions

Webhook permissions are attached to the token — user or company — that created the subscription.

A subscription never receives payloads that its creating token would not be permitted to see through the API or the Factorial UI. This prevents users from accessing information they are not allowed to see by routing it through a webhook subscription.

For example, a timeoff/leave/create subscription created with a user token will not receive time-off requests from other employees if that user cannot see their time-off leaves in Factorial.

📘
Avoiding permission-scoped gaps
Use a company token or an API key when the integration needs to see events across the whole company. If deliveries seem to be missing for some employees but not others, the creating token's permissions are the first thing to check.

Next step

See Best Practices & Troubleshooting for how to build a handler that survives retries and how to diagnose missing deliveries.