Webhooks Policies

Notification and retries

To allow the service to recover from potential temporary errors on your end, we have implemented a retry policy of up to 20 attempts over the 48 hours following the event you
are subscribed to.

If the request is unsuccessful, in retries #1, #5, #10 and later, you will be notified of this issue via email.

After the maximum number of retries or the maximum allowed time has been reached, you will receive a final email notification, and the subscription will be disabled.
If the issue in your service is resolved, you can reactivate the subscription by following the instructions described in Enabling or Disabling a
subscription.

Email recipient resolution

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

1. Partner email — from the marketplace integration linked to the OAuth application
2. Technical support contact — the email configured by the company in Settings → API Notifications (see Configuring the technical support contact)
3. OAuth application owner — the user who owns the OAuth application that created the subscription
4. Subscription author — the user who originally created the webhook subscription
5. 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 email address that receives API notifications (webhook failures and automatic disabling events), so that alerts reach the team responsible for the integration.

To configure it:

1. Go to Settings (e.g. https://app.factorialhr.com/settings/).
2. Open the API Notifications section.
3. Enter the email address that should receive API notifications in the Technical support contact field.
4. 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.

Webhook permissions

Webhook permissions are attached to the token (user or company) that created the webhook subscription.

This means subscriptions won't get webhook payloads they should not have the permission to see. This prevents users from accessing information that they are not allowed, through webhook subscriptions

For instance, in the case of timeoff/leave/createa webhook subscription created with a user token won't get timeoff requests from other employees if this user cannot see employee timeoff leaves in Factorial UIs.

You can always use a company token or API keys to avoid these restrictions.