A HTTP callback (also known as a Webhook) is an HTTP POST that occurs when something happens: a simple event-notification via HTTP POST.

The Kudoz API allows its clients to receive HTTP Callbacks on a predefined set of events. When such event happens, the Kudoz servers issue a POST request to the client server. For example, by registering a callback, a recruiter can be notified immediately whenever a candidate applies to one of their jobs.

URL

The callback URL is client defined. API clients have to set a callback URL in order to be able to receive callback requests. This is possible by liaising with the support.

Payload

The HTTP callback request payload has the following structure:

{
  "id": "f5f422af-046e-4db8-aaa8-5a89f96a2e63",
  "kind": "event_kind",
  "data": {
    ...
  }
}
  • id the unique event identifier.
  • kind the callback event kind. Example value: job_application.
  • data optional object that holds any data relevant to the event that triggered the callback.

Authentication

Callbacks have the same authentication scheme as the one used by clients to access the Kudoz API: the HTTP Authentication header contained in the callback request conforms to the following format:

Authorization: TOKEN {Api Key}:{Random Unique UUID}:{Timestamp}:{Authentication Token}

The API key/secret used for callbacks is selected by the client form his set of valid API key/value pairs. It can be changed at any time by liaising with the support.

Job Application Callback

This callback is triggered when a candidate applies to one of the client’s jobs. The event kind is set to job_application. The data contains:

  • offer_referece: the client reference of the offer that is being applied to,
  • recruiter_email: the email of the recruiter tha have issued the job ad,
  • job_application_id: the job application identifier in the Kudoz systems,
  • cover_message: the candidate’s motivation message, and
  • candidate: the full candidate profile.

Example

{
  "kind": "job_application",
  "data": {
    "job_reference": "O-dfw18",
    "recruiter_email": "phil@acmecorp.com",
    "job_application_id": 345678986,
    "cover_message": "Votre offre a retenue toute mon attention. Passionné par l'univers RH, j'aimerais avoir la possibilité de vous rencontrer lors d'un entretien",
    "candidate": {
      "id": 48447,
      "email": "jack@example.com",
      "headline": "Recherche poste Communication / RP / Partenariats",
      "first_name": "Jack",
      "last_name": "Dupont",
      "location": "Région de Paris , France",
      "pictures": [
        "https://media.licdn.com/mpr/mpr/shrinknp_200_200/AAEAAQAAAAAAAANcAAAAJDU5ZDRiNTA2LWM1ZWItNDVlOC04MTZmLTlhNDljZGQzMDVlOQ.jpg"
      ],
      "birthday": "1989-01-01",
      "summary": "Commercial B2B Senior",
      "phone_number": "33699999999",
      "social_profiles": {
        "linkedin": "https://www.linkedin.com/in/pierre-herv%C3%A9-0a609931"
      },
      "resume": "https://api.getkudoz.com/v5/candidates/48447.pdf?token=xyz123789834"
    }
  }
}