Overview

Webhooks are a system of automated notifications indicating that an event has occurred in your account. Rather than requiring you to pull information via our APIs or to make API calls periodically to check status of various events, webhooks push information to your destination as and when the events occur.

After you've subscribed to the webhooks, you can let your app execute code immediately after specific events occur in your account at HackerEarth. For example, you can rely on webhooks to trigger an action in your app when a candidate begins or ends an assessment, or when a candidate report or an assessment config gets updated at HackerEarth.

By using webhooks, you would be making fewer API calls overall, which makes sure that your apps are more efficient and update quickly.

Webhooks Endpoint

Only a single endpoint can be configured per company account and that endpoint would be receiving webhooks for all types of events. You can get this endpoint configured by reaching out to api@hackerearth.com.

To correctly handle events delivered to your webhooks endpoint, please take care of the following points when designing your application:

• Webhooks endpoint must accept HTTPS connections using TLS v1.2 or higher.
• Webhooks endpoint must accept POST requests as HackerEarth uses POST requests to deliver events to the endpoint.
• Events are not guaranteed to be delivered only once.
• Events are not guaranteed to be delivered in chronological order.
• If HackerEarth does not receive a 2xx response within 10 seconds of posting an event to the webhooks endpoint, then it will retry 3 more times with a delay of 2 hours between each attempt.

Webhooks event structure

An incoming webhooks message contains the following information:

1. An HTTP header which contains signature related information. This has been explained in the Authentication section.
2. A HTTP body containing a JSON message which consists of four fields: webhook_event_id, webhook_event_type, webhook_attempt_number and webhook_payload. These have been explained below.

Sample Webhook request body

{
    "webhook_event_id": "49f6b922b2feee3be3ec79e88d6ff36",
    "webhook_event_type": "CANDIDATE_TEST_STARTED",
    "webhook_attempt_number": 1,
    "webhook_payload":{
        "test_id": 1035542,
        "email": "alice@bob.com",
        "start_datetime": "2019-08-05T10:11:46-05:51"
    }
}

webhook_event_id

Type: String

Description: webhook_event_id would be a universally unique identifier (UUID) for the webhook event.

webhook_event_type

Type: String

Description: webhook_event_type would be an enum indicating the type of webhook event.

webhook_attempt_number

Type: Integer

Description: webhook_attempt_number would be the attempt count of a webhook request. It's value would be 1 for the initial request and would get incremented in case of retries.

webhook_payload

Type: Dictionary (JSON)

Description: webhook_payload would contain the details corresponding to the webhook event.