Webhooks

KeldairHR uses webhooks to notify your application when an event happens in your ATS. Webhooks are particularly useful for asynchronous events like when an applicant get hired, or an onboarding file gets completed.

📘

Ready to go live?

Register your webhook endpoint with the KeldairHR product team so we knows where to deliver events.

What are webhooks?

A webhook enables KeldairHR to push real-time notifications to your app. KeldairHR uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Steps to receive webhooks

1. Identify the events you want to monitor and the event payloads to parse.
2. Create a webhook endpoint as an HTTPS endpoint (URL) on your server.
3. Handle requests from KeldairHR by parsing each event object and returning 2xx response status codes.
4. Test that your webhook endpoint is working properly.
5. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
6. Register your publicly accessible HTTPS URL with the KeldairHR product team.

What is a webhook endpoint?

It’s an HTTPS endpoint on your server with a URL. You can use one endpoint to handle several different event types at once.

Steps to process webhooks

Step one: Identify the events to monitor

Identify the type of events and the event objects your webhook endpoint needs to parse.

Step two: Create a webhook endpoint

Set up an HTTP endpoint on that can accept unauthenticated webhook requests with a POST method.

Step three: Handle requests from KeldairHR

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. KeldairHR sends events to your webhook endpoint as part of a POST request with a JSON payload.

Check event objects
Each event is structured as an event object with a type, id, version, dateOccurred, and related KeldairHR resource nested under data. Your endpoint must check the event type and parse the payload of each event.

{
  "id": "4183db97-6805-411f-b8fd-325cbf5ed90f",
  "type": "resource.event",
  "version": "2022-02-23",
  "dateOccurred": "2022-02-23T18:46:43+00:00",
  "data": {...}
}

Return a 2xx response
Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating an employee record in your payroll system.

Built-in retries
KeldairHR webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If KeldairHR doesn’t quickly receive a 2xx response status code for an event, we mark the attempt as failed and periodically will retry it up to 24 hours.

Step four: Secure your webhooks (recommended)

Use webhook signatures to verify that KeldairHR generated a webhook request and that it didn’t come from a server acting like KeldairHR .