Push events augment iCIMS API functionality with the ability to deliver real-time notifications to interested parties when important events take place within the Platform. This is opposed to a polling-based system where an external system must repeatedly query iCIMS API in order to determine if any changes have taken place. Instead, the Platform and iCIMS API will track these changes and send out notifications (as desired/configured) to indicate that changes have occurred.  

After logging in to the Platform, the system can be configured to deliver push notifications for a variety of different events that may occur within the Platform. To deliver these push events, the system must be configured through the Event Notifications page, where users include the URLs to push to.

Push events will be delivered via GZIP'd RESTful JSON over HTTPS through the POST method.

Partners are expected to reply with HTTP 200 OK if they successfully process the message without errors. Partners will be able to reply with HTTP 303 See Other in response to certain messages where link responses are required. Partners are expected to reply with HTTP 400 Bad Request if the message is malformed or otherwise incorrect.

iCIMS requires that all communication is done over https with a valid SSL certificate. Self-signed certificates cannot be used. OAuth 2.0, HMAC, and Basic Authentication are available for outbound event notifications.

To support OAuth 2.0 the Access Token URL, Client ID and Client Secret must be provided. The OAuth server token endpoint must adhere to the OAuth 2.0 client credentials grant flow.

An example of the expected Authorization Response is below.

HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"eyJz93a...k4laUWw",
"token_type":"Bearer",
"expires_in":86400
}

iCIMS requires all event notifications to be processed with the fail-fast pattern. We have identified scenarios that an integration must handle to provide a reliable user experience.

Scenario 1: Successfully Processed Event Notification

iCIMS expects the 3rd party to process the event notification in a single transaction. The transaction should be ACID compliant.

Scenario 2: Duplicate Request

A user can generate multiple event notifications for the same action. The 3rd party system must handle duplication requests and not treat each request as a new request. Each event notification has identifiers that can be used to detect duplicate requests.

Scenario 3: Failure Caused by User Action (Missing Fields, Incorrect Package Selection, Etc.)

If the 3rd party platform cannot validate information provided by the user, it must return 400 for user error with a user actionable error message in the response’s payload. If the error cannot be corrected by the user, the system must return a 500 error. Please refer to Error Reporting Standards for Vendors for more details.

The user is expected to fix the issue and try again or reach out to support.

Scenario 4: Failure to Connect to 3rd Party Platform

If iCIMS is not able to communicate with the 3rd party platform, it will record the failure and notify the user. The user is expected to try again, but if the failure persists, the user will need to reach out to support.

Scenario 5: Failure to Receive Confirmation from 3rd Party Platform

If iCIMS is not able to receive the confirmation message to the event notification, it will record the failure and notify the user. The user is expected to try again but if the failure persists, the user will need to reach out to support.

It’s important for the 3rd party to recognize this type of a failure and for the 3rd party’s duplicate request checking logic to account for this scenario. The record in the 3rd party platform will already exist, but the user, upon trying again, will be notified that the request was processed. Duplicate check should prevent duplicate records from being created.

Scenario 6: Unknown Failure

If unusual behavior is observed, iCIMS will record the failure and notify the user. The user is expected to try again, but if the failure persists, the user will need to reach out to support.

Upon retrying, either the transaction will have been processed by the 3rd party—in which case, it will be treated as a duplicate request—or it will be the first time the 3rd party has encountered the request, in which case, it will be treated as a new transaction.

iCIMS expects event notifications to be processed within 30 seconds. If iCIMS does not receive a response within 30 seconds, it will treat it as an unknown failure. Users at this point will be asked to try again and the 3rd party is expected to prevent duplicate records from being created.

To prevent excessive response times, the 3rd party should do the minimal work required to be processed synchronously. Additional work that does not impact user experience should be scheduled asynchronously.

When developing an integration based on event notifications, you should keep in mind who the actor is. Some event notifications will be triggered by recruiters and others will be triggered by candidates and new hires. When the system is unable to process the event notification, it should present an error message appropriate to the actor. Integrations should not ask candidates and new hires to fix things that they will not have access to. The application complete event notification enhances the application process. This event notification should be built as failsafe as possible. Presenting errors during this process will degrade the candidate experience, ultimately resulting in the recruitment organization to observe an increase in candidate drop off rate.

The party writing the integration is ultimately responsible for the correctness and reliability of the integration. The following are recommended guidelines based on best judgment of those responsible for the documentation.

Here we describe how an ACID compliant transaction to handle event notifications can be implemented. The strategy described below relies on a Relational Database Management System (RDBMS) that is ACID compliant.

We start the transaction by reading from remote systems and validating the input before any data is written. Once input has been validated, appropriate records are created and/or updated. If actions need to be taken on systems outside of the RDBMS’ transaction, a scheduler that can schedule tasks within the RDBMS’ transaction should be used. Tasks to update systems outside of the RDBMS transaction should be scheduled within the RDBMS’ transaction. If no issues occur, the transaction is committed. Otherwise, it is rolled back.

Quartz is an example of a scheduler that can schedule tasks within a RDBMS transaction. The input validation should ensure that systems outside of the RDBMS transaction will not run into validation issues when the scheduled tasks execute. The scheduled task should be executed asynchronously and retry logic with failure handling should be implemented.

1. An ACID compliant RDBMS is used and a transaction is started.
2. Within the transaction, the system checks to see if it has processed this event notification before. We recommend creating a “record table” with unique identifiers as primary keys to ensure that each event notification is processed only once. The system will react accordingly depending on if the duplicate request is detected or not. Refer to the “Reliably Handling Event Notifications” section for more information.
3. Information is gathered from systems outside of the RDBMS’ transaction.
4. Information is gathered from systems inside of the RDBMS’ transaction. This is done after external systems are read to reduce the time that read locks are held.
5. Information is validated to ensure that this system and any downstream systems will be able to process the information.
6. Records are created and updated and a new row is created in the “record table” to prevent duplicate processing of the event notification. If another transaction that has processed the event notification has successfully committed, the RDBMS will fail this transaction and rollback changes due to primary key violation.
7. If additional systems that resides outside of the RDBMS’ transaction need to take action (e.g., email system), a scheduling tool can be used schedule the task within the transaction and trigger the action outside of the transaction asynchronously.
8. The transaction is committed.