웹훅 연동

◼ 기능 제공 요금제 : 엔터프라이즈

나인하이어 웹훅 소개

나인하이어 웹훅은 나인하이어에서 지원자 데이터가 변경되었을 때, 서버에서 실시간으로 알림을 받을 수 있는 기능입니다.

웹훅(Webhook)이란 특정 이벤트가 발생했을 때 타 서비스나 응용프로그램으로 알림을 보내는 기능입니다. 웹훅 프로바이더는 해당 이벤트가 발생하면 HTTP POST 요청을 생성하여 URL(endpoint)로 이벤트 정보를 보냅니다. 웹훅을 사용하면 특정 이벤트가 발생했을 때에만 지정한 URL로 관련 이벤트 정보를 수신할 수 있어, 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어 리소스나 통신 측면에서 효율적입니다.

나인하이어 웹훅 활용

나인하이어 웹훅은 지원자 최종합격, 불합격, 불합격 취소 등 지원자의 상태 변경시 해당 지원자에 대한 데이터를 받아보실 수 있는 기능을 제공하고 있습니다. 등록된 지원자가 합격 또는 불합격 시 해당 지원자들의 데이터를 사내 인사관리 ERP등에 등록하실 때 활용하실 수 있습니다.

나인하이어 웹훅은 장애가 발생하여 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우, 웹훅을 재전송하지 않습니다.

나인하이어 웹훅 연동 방법

현재 나인하이어 내 웹훅 페이지에서 신규 웹훅 등록/수정 기능 사용이 중단되어 있습니다.

신규 웹훅 등록/수정이 필요하시다면, 나인하이어팀에 문의하시어 등록을 요청해 주세요.

문의하실 때 사용하실 웹훅 URL과 이벤트를 전달해 주시면 빠르게 검토하여 등록을 도와드릴 수 있습니다.

(1) 수신을 원하는 웹훅의 이벤트 타입을 선택해 주세요.

웹훅 이벤트	이벤트 설명
지원자 합격	진행중인 지원자가 해당 채용의 [최종 합격] 단계로 이동하는 경우 이벤트가 발생합니다.
지원자 합격 취소	[최종 합격] 단계에 있는 지원자가 해당 채용의 다른 단계로 이동되는 경우 이벤트가 발생합니다.
지원자 불합격	진행중인 지원자가 [불합격] 상태가 되는 경우 이벤트가 발생합니다.
지원자 불합격 취소	불합격된 지원자의 [불합격 취소] 시 이벤트가 발생합니다.

지원자 합격 및 불합격 이벤트는 지원자를 다중 선택하여 처리할 때에도 발생하므로, 일괄 합격 또는 불합격 처리 인원수에 따라 동시에 많은 웹훅이 수신될 수 있음을 고려하여 주시기 바랍니다.

(2) 웹훅 이벤트를 등록하세요.

서비스 연동 > 데이터 > 웹훅 탭에서 웹훅을 등록하실 수 있습니다. 이름과 URL을 입력하고 등록할 이벤트를 선택한 후 [완료] 를 누르면 웹훅이 등록됩니다.

(3) 등록한 웹훅을 테스트해 보세요.

웹훅은 나인하이어에서 실시간으로 테스트해보실 수 있습니다. 기본적으로 웹훅 테스트는 외부망에서 접근이 가능한 도메인만 가능합니다. 로컬 개발 환경의 경우 외부에서 접근이 불가능하기 때문에 로컬 서버 포트가 포함된 URL (localhost 등)은 웹훅으로 등록하실 수 없습니다. 로컬 개발 환경에서 웹훅 테스트가 필요하신 경우 ngrok 등을 이용하시어 테스트를 진행해 주세요. 웹훅 전송 시 응답으로 HTTP 2xx 코드가 돌아오면 전송 성공으로 간주합니다.

웹훅 이벤트는 JSON 형식으로 전송됩니다. 서버에서 JSON을 처리할 수 있는지 확인해주세요. 수신 URL은 HTTP도 지원하지만, 보안이 강화된 HTTPS 통신을 권장합니다.

이벤트 응답 상세

Webhook HTTP Headers

Key	Value
user-agent	ninehire/webhook
content-type	application/json

Response

지원자 웹훅은 이벤트 타입에 상관 없이 모두 동일한 지원자 객체를 전달합니다.

[응답 예시]

{
  "id": "83358d40-dd80-11ec-a5e3-dfd033b91127",
	"status": "passed",
  "appliedAt": "2023-02-24T05:30:11.162Z",
  "updatedAt": "2023-02-24T05:30:11.162Z",
  "name": "김준식",
  "email": "[e-mail]",
  "phoneNumber": "01012341234",
  "source": "채용홈페이지",
  "recruitment": {
    "id": "22358d40-dd80-11ec-a5e3-dfd033b91127",
    "title": "UI/UX 디자이너 채용"
  },
	"step": {
    "id": "a0fd1f01-16dd-11ed-b364-17ed2b629a55",
    "type": "passed",
    "title": "최종 합격"
  },
  "customAnswers": [
    {
      "title": "이력서",
      "content": null,
      "fileTitle": "이력서",
      "fileExtension": "pdf",
      "fileUrl": "https://file.ninehire.com/application/86892cf0-ef6e-11eb-bc61-f1d15c5aab31/attachment/772dd7e0-f038-11eb-bd0f-7538518f88d5.pdf"
    },
    {
      "title": "희망 연봉",
      "content": "4,000만원",
      "fileTitle": null,
      "fileExtension": null,
      "fileUrl": null,
    }
  ],
  "educations:": [
    {
      "type": "university",
      "schoolName": "서울대학교",
      "passedAt": null,
      "enteredAt": "2008-02-29T15:00:00.000Z",
      "graduatedAt": "2012-07-31T15:00:00.000Z",
      "grade": "3.69/4.5",
      "major": "시각디자인",
      "status": "drop_out",
			"nightClass": true,
    }
  ],
  "experiences": [
    {
      "companyName": "나인하이어",
      "joinedAt": "2021-01-14T15:00:00.000Z",
      "leftAt": "2023-01-14T15:00:00.000Z",
      "employmentType": "contractor",
      "position": "사원",
      "department": "full_time",
      "task": "채용 솔루션 전반 디자인 업무"
    }
  ],
  "licenses": [
    {
      "type": "license",
      "title": "웹퍼블리셔",
      "publisher": "NCS",
      "grade": "302",
      "publishedAt": "2013-01-11T01:51:18.000Z"
    }
  ],
  "languages": [
    {
      "type": "english",
      "testTitle": "TOEIC",
      "publisher": "한국토익위원회",
      "grade": "970",
      "publishedAt": "2015-01-11T01:51:31.000Z"
    }
  ],
  "militaryService": {
    "type": "fulfilled"
  },
  "veteranStatus": { "type": "no", "number": null },
  "disability": { "type": "physical", "degree": "serious" },
	"gender": "male",
	"birthday": "1995-01-14T15:00:00.000Z",
}

키	타입	비고	설명
id	string		지원자별 고유한 ID 값입니다.
status	string		지원자의 상태 정보입니다. passed : 최종 합격 progressing : 진행 중 failed : 불합격
appliedAt	string(datetime)		지원서를 접수한 날짜와 시간 정보입니다.
updatedAt	string(datetime)		지원자의 최종 상태 업데이트 날짜와 시간 정보입니다.
name	string		지원자의 이름입니다.
email	string		지원자의 이메일입니다.
phoneNumber	string		지원자의 전화번호입니다.
source	string	nullable	지원자가 지원시 입력한 지원 경로입니다.
recruitment	object		지원자가 접수한 채용 정보입니다. (Recruitment Object)
step	object		지원자의 단계 정보입니다. (Step Object)
customAnswers	object[]		지원서의 커스텀 항목별 지원자의 답변 내용입니다. (CustomAnswer Array)
educations	object[]		지원서의 경력사항 항목에 대한 지원자의 답변 내용입니다. (Education Array)
experiences	object[]		지원서의 학력사항 항목에 대한 지원자의 답변 내용입니다. (Experience Array)
licenses	object[]		지원서의 자격증/수상 항목에 대한 지원자의 답변 내용입니다. (License Array)
languages	object[]		지원서의 어학 항목에 대한 지원자의 답변 내용입니다. (Language Array)
militaryService	object	nullable	지원서의 병역사항 항목에 대한 지원자의 답변 내용입니다. (MilitaryService Array)
veteranStatus	object	nullable	지원서의 보훈여부 항목에 대한 지원자의 답변 내용입니다. (VeteranStatus Array)
disability	object	nullable	지원서의 장애여부 항목에 대한 지원자의 답변 내용입니다. (Disability Array)
birthday	string(datetime)	nullable	지원자의 생년월일입니다.
gender	string	nullable	지원자의 성별입니다. male : 남성 female : 여성

Recruitment

키	타입	비고	설명
id	string		채용 별 고유한 ID 값입니다.
title	string		채용명 입니다.

Step

키	타입	비고	설명
id	string		단계별 고유한 ID 값입니다.
title	string		단계명 입니다.
type	string		단계 정보입니다.

CustomerAnswer

키	타입	비고	설명
title	string		질문 내용입니다.
content	string	nullable	지원자의 텍스트 답변 내용입니다.
fileTitle	string	nullable	지원자가 제출한 파일명입니다.
fileExtension	string	nullable	지원자가 제출한 파일의 확장자입니다.
fileUrl	string	nullable	지원자가 제출한 파일의 URL입니다.

Education

키	타입	비고	설명
type	string		학력 구분입니다. qualification_exam : 검정고시 high_school : 고등학교 technical_college : 전문대학 university : 대학교(4년이상) master_course : 대학원(석사) doctorate_course : 대학원(박사)
schoolName	string	nullable	학교명 입니다.
passedAt	string(datetime)	nullable	합격년월 입니다.
enteredAt	string(datetime)	nullable	입학년월 입니다.
graduatedAt	string(datetime)	nullable	졸업년월 입니다.
grade	string	nullable	학점/기준학점 입니다.
major	string	nullable	주전공 입니다.
status	string	nullable	졸업상태 입니다. graduation : 졸업 drop_out : 중퇴 leave : 휴학 candidate : 졸업예정 attending : 재학중 completion : 수료
nightClass	boolean		야간대학 여부입니다.

Experience

키	타입	비고	설명
companyName	string		회사명 입니다.
joinedAt	string(datetime)		입사일 입니다.
leftAt	string(datetime)	nullable	퇴사일 입니다.
employmentType	string		고용형태 입니다. full_time : 정규직 contractor : 계약직 intern : 인턴 etc : 기타
position	string		직급/직책 입니다.
department	string		근무부서 입니다.
task	string		담당업무 입니다.

License

키	타입	비고	설명
type	string		자격 구분입니다. licence : 자격증 prize : 수상
title	string		자격증/수상명 입니다.
publisher	string		주최기관/발행처 입니다.
grade	string		점수/급 입니다.
publishedAt	string(datetime)		취득일 입니다.

Language

키	타입	비고	설명
type	string		언어 타입입니다. english : 영어 japanese: 일본어 chinese: 중국어 spanish : 스페인어 german : 독일어 french : 프랑스어 vietnamese : 베트남어 russian : 러시아어 indonesian : 인도네시아어 thai : 태국어 etc : 기타
testTitle	string		시험명 입니다.
publisher	string		주최기관 입니다.
grade	string		점수/급 입니다.
publishedAt	string(datetime)		취득일 입니다.

MilitaryService

키	타입	비고	설명
type	string		병역 구분 입니다. fulfilled : 군필 unfulfilled : 미필 in : 복무중 exemption : 병역면제 none : 해당없음

VateranStatus

키	타입	비고	설명
type	string		보훈 구분 입니다. yes : 대상 no : 비대상
number	string	nullable	보훈 번호 입니다.

Disability

키	타입	비고	설명
type	string		장애 구분 입니다. none : 해당없음 physical : 지체장애 encephalopathy : 뇌병변장애 visual : 시각장애 hearing : 청각장애 speech : 언어장애 facial : 안면장애 intellectual : 지적장애 mental : 정신장애 autism : 자폐성장애 kidney : 신장장애 heart : 심장장애 repiratory : 호흡기장애 liver : 간장애 stoma : 장루/요루장애 epilepsy : 뇌전증장애
degree	string	nullable	장애 정도 입니다. slight : 경증 serious: 중증 etc : 기타