What are they?

📘

"Knock knock on X outside Factorial when Y happens inside Factorial"

🚧

Usage

Webhooks can be used directly or via intermediary platforms or services. Using them directly requires technical knowledge.

Webhooks allow you to build or set up integrations, such as sync between platforms or perform an action after a specific event happens. When one of those events is triggered, a HTTP POST payload will be sent to the webhook's configured URL. Webhooks can be used to update an external LDAP, trigger processes, update another application, or even connect to another platform to perform other events. You're only limited by your imagination...and technical knowledge.

Factorial Webhooks

Thousands of things are constantly happening inside Factorial without anyone knowing when they happen and that's ok, knowing all of them is not useful and will probably serve for confusion.
But there are a few that are useful to know. We require knowing the moment this events happen and any related information. Thats why, there's are endpoint available where URLs can be associated to different events.

🚧

Url

The same URL can be used to get notifications for all events or different ones per event. Notice that if the same url for receiving notifications is used for all events, then distinguishing an event from another might be an issue.

When an event happens inside Factorial, a POST request will be triggered to the associated event URL. If the request fails for any given reason, a retry will be performed shortly after.

Subscribe

Subscribing to a webhooks is fearly simple although technical knowledge is required. After getting an Oauth2 token or an ApiKey credential, a simple curl request with the event id and the url is all that is required.

curl --request POST \
     --url https://api.factorialhr.com/api/v1/webhooks \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "type": "employee_unterminated",
     "target_url": "https://foo.com/webhooks/employee_unterminated"
}
'

🚧

Existing webhook

If a webhook to an event already exists, creating a new subscription will overwrite the previous subscription.

Unsubscribe

To delete a webhooks or stop a subscription to an event, simply do a DELETE request with the event id.

curl --request DELETE \
     --url https://api.factorialhr.com/api/v1/webhooks \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "type": "employee_invited"
}
'

List

To display current configured webhooks perform the following curl. (more info on the api documentation)

curl --request GET \
     --url https://api.factorialhr.com/api/v1/webhooks \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer TOKEN'

Challenge

When a webhook challenge is created during the creation of a webhook. We send back that challenge in the header of the requests as x-factorial-wh-challenge

This allows various validation mechanism to be used to ascertain that the request is originating from the subscription that was created earlier