Teamtailor offers a robust Webhook functionality that allows you to subscribe to updates, creations, and destruction events related to candidate profiles, job applications, jobs, audit events, and more.
This article expects that you have the basic knowledge of how Webhooks works and will guide you on how to effectively set up Webhooks within Teamtailor and leverage their power. Additionally, this solution is also dedicated to partner integrations, so if you are a partner looking to develop Webhook-based integration, please reach out to us for further assistance.
Contact support@teamtailor.com and let us know that you would like to activate the webhook feature.
Creating Webhooks in Teamtailor:
After activating the webook feature via support@teamtailor.com, you can follow these steps:
1. Access Webhooks Configuration: Log in to your Teamtailor account and navigate to the "Settings" section. From there, select "Webhooks" and click on "New Webhook."
2. Define Webhook Details: Provide a meaningful name for your webhook to help identify its purpose. You can also add an optional description to provide further context.
3. Specify the Endpoint URL: Enter the URL of the endpoint in your application where you want to receive the webhook payloads. Make sure the endpoint is secure and can handle incoming requests.
4. Select Event Types: Choose the specific event types you want to subscribe to. Teamtailor offers a wide range of events, including candidate updates, job application creations, job deletions, and audit events. To include custom field updates on jobs and candidates you will need to subscribe to those as well. Select the ones that are relevant to your integration.
5. Save the Webhook: After specifying the details and event types, click on "Save" to create the webhook. You can also test the webhook to ensure that it is correctly configured and receiving payloads.
Calculating Webhook Signatures:
To ensure the integrity and authenticity of webhook payloads, Teamtailor supports webhook signatures. The signature can be calculated using various programming languages. Here are examples of how to calculate the signature in Ruby and Node.js:
Ruby:
require 'openssl'
def calculate_signature(signature_key, resource_id)
signature = OpenSSL::HMAC.hexdigest("sha256", signature_key, resource_id)
Base64.strict_encode64(signature)
end
```
Node.js:
const crypto = require('crypto');
function calculateSignature(signatureKey, resourceId) {
const hmac = crypto.createHmac('sha256', signatureKey);
hmac.update(resourceId);
const signature = hmac.digest('hex');
return Buffer.from(signature).toString('base64')
}
In the code snippets above, `signature_key` is a unique secret key provided by Teamtailor during webhook creation, and `resource_id` is the ID of the resource associated with the webhook event. The `calculate_signature` function returns the calculated signature as a base64 string.
Validating Webhook Signatures:
Upon receiving a webhook payload, you can validate the signature to ensure its authenticity. Follow these steps to validate the signature:
1. Retrieve the Signature Key: Safely store the signature key provided by Teamtailor during webhook creation.
2. Extract the Signature and Resource ID: From the received webhook payload, extract the signature and the associated resource ID.
3. Recreate the Signature: Using the respective signature calculation function, compute the signature by passing the signature key and the extracted resource ID.
4. Compare Signatures: Compare the recreated signature with the extracted signature. If they match, the payload's integrity and authenticity are confirmed.
Handling Webhook Payloads and Retries:
Once the webhook is set up, and the signature is validated, you can extract the relevant data from the webhook payload and process it in your application. The resource ID will be part of each payload, allowing you to identify the associated resource and perform the necessary actions.
Additionally, it is crucial to handle the response appropriately when processing the webhook payload. Teamtailor expects a 200 response status code to confirm the successful receipt of the webhook payload. However, in cases where the response status code is greater than or equal to 400, indicating an error, Teamtailor will retry 3 times
To handle webhook payload responses:
1. Upon receiving a webhook payload, your application should respond with a 200 status code to acknowledge successful receipt. This informs Teamtailor that the payload was delivered successfully.
2. If your application encounters an error or receives a response with a status code greater than or equal to 400, it should trigger a retry mechanism.
By implementing retries, you can mitigate temporary issues such as network connectivity problems or server errors that may have caused the initial unsuccessful response.