Getting started with the Events Webhook🔗
Textkernel's Events Webhook notifies a configured URL via HTTP POST with information about events that occur in several Textkernel products. You typically want to consume and handle these events in your ATS/HRIS platform to feed downstream automated workflows.
You set up the Events Webhook endpoint so that you consume these Events before Textkernel expires them. The Automation API retains Event data for up to 14 days. After that time passes, your event data is deleted from the Automation API servers.
The Events Webhook works with heterogeneous event streams, where events are delivered as batches. This means that different event types can be part of the same batch. Batches are sent either when the batch size limit is reached, or after a wait time limit even if the batch size limit is not reached. The wait time limit manages the delay between event creation and event delivery, and may result in sending batches with a single event.
Event types are versioned, and the webhook must be able to handle different event types and versions of event types. All events contain a payload that is specific per event type/version. Some event types have related binary content (e.g. CV files).
In this case, the binaries are not included in the payload. Instead there is a separate endpoint where the binaries can be retrieved, once you are notified of their existence by the webhook event. The existence of binaries related to an event is deduced by the presence of the binaries optional field in the payload field of the event object. The structure of the binaries field is event type/version specific and is described in the specification of the respective event types. The endpoint for retrieving the binaries requires OAuth authentication.
Webhook implementation is expected to gracefully handle event types/versions that it either does not support or is not interested in, i.e. they should be discarded rather than causing an error.
The purpose of the webhook is to consume the events, not to process the payload. Therefore, there is a strict time response limit described later in this document.
The webhook response concerns the consumption/receipt of events and is not related to event processing inside the ATS. In other words, it is related to the consumption of the entire batch, and not about processing of the individual events. All events in the batch where an error response was received would be re-sent.
Note that there is no guarantee of all events being re-sent in the same batch, since the events are unordered, and there is no order guarantee in this API. If the client is interested in the chronology of the events, the created field of the event should be used.
Enable your webhook endpoint🔗
To enable your webhook, notify the Textkernel Professional Services team about your credentials and URL details.
Webhook request🔗
The Automation API sends events to your webhook endpoint as part of a POST request with a JSON body. Content-type is 'application/json'.
Your endpoint must be configured to read event objects for the type(s) of event notifications you want to receive.
The request body contains an unordered list of events, where each event is an object with the following fields:
| Name | Description |
|---|---|
| type | the type and the version of the event |
| id | Textkernel's unique identifier for this event |
| created | date time in ISO-8601 format, in the UTC timezone |
| payload | JSON payload. The structure will depend on the event type |
Example of Events JSON Structure for a candidate_import event
[
{
"id": "c6de0fed-4cd2-4d03-909d-a1812d7c7e81",
"type": "candidate_import/v1",
"created": "2022-06-05T14:48:00.000Z",
"payload": "the payload for candidate_import event"
}
]
Consuming Automation API events🔗
Event Batch Limit🔗
The events are grouped together into batches. By batching the events, it is possible to control how often the webhook makes API calls into the integrated ATS/HRIS/CRM platform. The inbound API call rate is important for systems that throttle inbound API calls. The batch size limit is configured by the Textkernel team, and can be discussed. Whenever the limit is reached, the set of accumulated events is sent via the webhook.
Event Time Limit🔗
In addition to the batch size limit there is also a time limit. When the time limit is reached, the webhook delivers the current batch of accumulated events even when the batch size limit has not been reached. The time limit ensures events are sent without waiting a very long time to accumulate enough to reach the batch limit. The time limit is also configured by the Textkernel team.
Event Versioning🔗
The events are versioned. In general, event types that a consumer does not want to support will not be sent. However, because a new event version could be published by the Textkernel webhook before it is supported by the consumer, the event consumer is required to gracefully handle unknown event types, i.e. to ignore them instead of failing.
Mixed Event Types in Batches🔗
The Automation API uses a mixed stream of events with different event types. Each event type supports one of the integration scenarios offered by the Automation API (e.g. external candidate import or automatic match). The event types contain different data, depending on what is relevant for the particular integration scenario.
Event Response Handling🔗
Each request is atomic: this means that your endpoint must accept all events within a request or reject all of them.
Your endpoint must return HTTP status code 2xx after successfully processing the request. The response body is ignored by the Automation API, so avoid including it.
When the consumer receives the events, they must process them asynchronously: any errors due to processing of the event payload are separate from events due to consuming the webhook. Any errors that the webhook might return to the Textkernel webhook service must be related to events consumption, not the events' payload processing. As a result of this protocol, Textkernel sets a response time hard limit. The default expected response time is 3 seconds and is configurable via an optional value in the connector settings with a maximum hard value of 30 seconds. Delivery of events is atomic, i.e. if the delivery of a batch of events fails, Textkernel considers that all the events were not successfully delivered. So the handling of events by the webhook must be idempotent: it is possible that some events could be sent more than once in separate batches.
The order of events is not guaranteed, i.e. if a batch of events failed to be delivered via the webhook, it is not guaranteed that when Textkernel reattempts delivery, the new batch will be identical to the failed batch. The order of events does not reflect the chronological order of the creation of events. If the consumer cares about the chronological order of events then they can use the created field of the event.
Delivery failure and retry🔗
Automation API considers webhook delivery to have failed when:
- Automation API did not receive any response within 3 seconds
- HTTP response status code is other than 2xx
In such cases Automation API will make several retries up to 2 days with an increasing backoff.
There is no guarantee that all events will be re-sent in the same batch.
Your endpoint should be idempotent since the same event can be re-sent several times.
After the last failed retry, the event will be marked as permanently failed and no more retries will be done.