• 기능 제공 요금제: 엔터프라이즈(유료)

• 기능 사용 권한: 나인하이어팀에 등록 요청 (3. 나인하이어 웹훅 연동 방법 참고)

1. 나인하이어 웹훅 소개

나인하이어 웹훅은 지원자의 합격·불합격 상태나 포지션의 공고 내용·진행 상태가 변경되었을 때, 고객사 서버에서 실시간으로 알림을 받을 수 있는 기능입니다.

웹훅(Webhook)이란 특정 이벤트가 발생했을 때 타 서비스나 응용프로그램으로 알림을 보내는 기능입니다. 웹훅 프로바이더는 해당 이벤트가 발생하면 HTTP POST 요청을 생성하여 URL(endpoint)로 이벤트 정보를 보냅니다.

웹훅을 사용하면 특정 이벤트가 발생했을 때에만 지정한 URL로 관련 이벤트 정보를 수신할 수 있어, 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어 리소스나 통신 측면에서 효율적입니다.

‼️ 사용 중인 메신저의 웹훅 URL 등록 시 주의사항

나인하이어에서 제공하는 Webhook Response와 Slack / Jandi 등 메신저의 Incoming Webhook Request Payload 형식은 구조적으로 일치하지 않아, 두 시스템을 단순히 연결했을 때 정상적으로 작동하지 않습니다.

왜 작동하지 않나요?

형식 차이: 나인하이어 Webhook Response는 JSON 구조로 데이터를 전달하지만, Slack / Jandi는 특정한 text, blocks, attachments 등의 메시지 포맷을 요구합니다.
역방향 흐름: 나인하이어는 “데이터를 보낸다”라는 개념이고, Slack/Jandi의 Incoming Webhook은 “메시지를 받는다”라는 개념으로, 중간 변환 과정이 필요합니다.

해결 방법

Slack / Jandi에 직접 연결하는 대신, 중간 변환 서버(시스템)가 필요합니다.

n8n, Zapier 같은 워크플로우 자동화 툴 사용
- 나인하이어 Webhook → n8n/Zapier → Slack Incoming Webhook 으로 전달
- 중간에서 JSON을 Slack 형식에 맞게 변환 후 전송
자체 서버 구축
- 간단한 API 서버를 만들어 나인하이어 Webhook을 받음
- 받은 데이터를 Slack/Jandi 요구 포맷으로 변환
- Incoming Webhook URL로 재전송

2. 나인하이어 웹훅 활용

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

포지션의 공고를 편집하거나 채용 진행 상태가 바뀌면 포지션 데이터를 받아, 자사 채용 사이트의 공고 정보를 갱신하는 데에도 활용할 수 있습니다.

⚠️ 나인하이어 웹훅은 전송에 실패하거나 수신 서버가 7초 안에 응답하지 않으면 다시 보내지 않습니다. 웹훅만으로는 데이터를 빠짐없이 받을 수 없으므로 7. 웹훅 누락 대비를 함께 적용해 주세요.

3. 나인하이어 웹훅 연동 방법

웹훅은 나인하이어팀이 등록해 드립니다. 아래 순서로 등록을 요청해 주세요.

웹훅을 받을 수신 서버를 준비하고, 사용할 이벤트와 이벤트별 수신 URL을 정해 주세요. (4. 웹훅 전송 방식과 수신 서버 요건 참고)
수신 URL과 이벤트를 나인하이어팀(고객센터 또는 담당자)에 전달해 주세요.
나인하이어팀이 검토·승인한 뒤 웹훅을 등록합니다. 나인하이어의 승인을 거친 URL만 등록할 수 있습니다.

수신 URL이나 이벤트를 변경할 때도 나인하이어팀에 요청해 주세요.

동일한 이벤트(예: 지원자 최종 합격, 불합격 등)에는 여러 웹훅을 연결할 수 없습니다.
나인하이어 API 주소(api.ninehire.com)는 수신 URL로 사용할 수 없습니다.

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

웹훅 이벤트	이벤트 코드	발송 시점
지원자 최종 합격	`applicant_passed`	지원자가 포지션의 [최종 합격] 단계로 이동했을 때. 개별 이동, 다중 선택 일괄 처리, 자동화 규칙에 의한 이동을 모두 포함합니다.
지원자 최종 합격 취소	`applicant_pass_canceled`	[최종 합격] 단계에 있던 지원자가 다른 단계로 이동했을 때
지원자 불합격	`applicant_failed`	지원자가 불합격 처리되었을 때. 개별·일괄·자동화 처리를 모두 포함합니다.
지원자 불합격 취소	`applicant_fail_canceled`	불합격 처리가 취소되었을 때. 개별·일괄 처리를 포함합니다.
공고 편집	`job_posting_updated`	공고 내용(본문·커버 이미지)을 편집해 저장했을 때
채용 진행 상태 변경	`job_status_updated`	포지션 상태 또는 공고 사용 여부가 실제로 바뀌었을 때. 접수 시작(바로 시작·예약 시작), 접수 마감(수동·예약·마감일 도래), 포지션 종료, 종료 취소, 보관, 보관 취소, 공고 사용 여부 변경을 포함합니다. 한 번의 동작에서 상태와 공고 사용 여부가 함께 바뀌어도 1건만 발송됩니다.

웹훅이 발송되지 않는 경우

이벤트	발송되지 않는 경우
지원자 최종 합격	지원자를 다른 포지션으로 이동하면서 이동한 포지션의 [최종 합격] 단계에 배치한 경우
채용 진행 상태 변경	포지션 상태와 공고 사용 여부가 바뀌지 않는 변경 (예: 접수 시작 예약 등록·삭제, 접수 마감 설정 변경, 채용 홈페이지 목록 노출 변경, 공고 사용 여부를 같은 값으로 다시 저장)
채용 진행 상태 변경	임시 저장·승인 대기 상태에서 시작한 동작 (포지션 생성·복사·승인)
공통	전송 시점에 대상 지원자 또는 포지션이 삭제된 경우
공통	해당 이벤트의 웹훅이 등록되어 있지 않은 경우

💡 신규 지원 접수(지원서 제출, 지원자 등록 API로 등록)에 대한 웹훅은 없습니다. 신규 지원자는 지원자 목록 조회 API로 주기적으로 조회해 주세요.

💡 포지션 종료를 취소하면 포지션 상태는 닫힘(disabled)이 되고, 접수 기간이 초기화되며, 공고 사용과 채용 홈페이지 목록 노출이 꺼집니다. 포지션 보관을 취소하면 포지션 상태는 종료(closed)가 됩니다.

💡 지원자 합격 및 불합격 이벤트는 지원자를 다중 선택하여 처리할 때에도 발생하므로, 일괄 합격 또는 불합격 처리 인원수에 따라 동시에 많은 웹훅이 수신될 수 있음을 고려하여 주시기 바랍니다. 자동화 규칙에 의한 처리도 포함되며, 지원자 1명당 1건씩 전송됩니다.

2) 수신 서버 준비

웹훅 수신 URL은 외부(인터넷)에서 접근할 수 있는 주소여야 합니다. 로컬 개발 환경은 외부에서 접근할 수 없으므로 로컬 서버 포트가 포함된 URL(localhost 등)이나 사설망 주소는 웹훅으로 등록하실 수 없습니다.

로컬 개발 환경에서 웹훅 테스트가 필요하신 경우 ngrok 등을 이용하시어 테스트를 진행해 주세요. 웹훅 전송 시 응답으로 HTTP 2xx 코드가 돌아오면 전송 성공으로 간주합니다.

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

4. 웹훅 전송 방식과 수신 서버 요건

1) 전송 방식

항목	내용
메서드	POST
헤더	`Content-Type: application/json;charset=UTF-8`, `User-Agent: ninehire/webhook`
본문	JSON (지원자 또는 포지션 데이터)
응답 대기 시간	최대 7초. 7초 안에 응답하지 않으면 실패로 처리됩니다.
리다이렉트	따라가지 않습니다. 3xx 응답은 실패로 처리됩니다.
성공 판정	HTTP 2xx 응답
재전송	없습니다. 실패하거나 시간이 초과되어도 다시 보내지 않습니다.
서명	없습니다. 서명·비밀키 검증용 헤더를 제공하지 않습니다.
전송 실패 시	웹훅 등록은 유지되며 비활성화되지 않습니다.
전송 시점	이벤트 발생 후 비동기로 전송됩니다.

💡 7초 시간 초과로 실패 처리된 경우에도 요청이 이미 수신 서버에 도달해 늦게 처리될 수 있습니다. 시간 초과가 곧 미수신을 의미하지는 않습니다.

2) 수신 서버 요건

외부(인터넷)에서 접근할 수 있는 https:// URL을 사용해 주세요.
요청을 받으면 즉시 2xx로 응답하고, 실제 업무 처리는 비동기로 진행해 주세요. 7초를 넘기면 실패로 처리되고 다시 보내지 않습니다.
리다이렉트(3xx)를 반환하지 말고, 최종 URL을 등록해 주세요.
같은 내용이 중복으로 오거나 이벤트 순서가 바뀌어 와도 결과가 같도록 처리해 주세요. 웹훅 데이터는 전송 시점의 현재 상태이므로, 지원자 ID(또는 포지션 ID) 기준으로 최신 상태를 덮어쓰는 방식이 적합합니다.
웹훅에는 서명이 없으므로 아래 보호 조치를 권장합니다.
- 추측하기 어려운 무작위 경로나 토큰을 URL에 포함 (예: https://hr.example.com/hooks/ninehire/8f3k2...)
- 요청 헤더의 User-Agent: ninehire/webhook 확인
- 중요한 처리 전에는 지원자 목록 조회·포지션 상세 조회 API로 다시 확인

3) 이벤트 구분 방법

웹훅 본문에는 이벤트 유형 정보가 없고, 지원자 이벤트 4개는 본문 구조가 모두 같습니다. 이벤트를 구분하려면 이벤트별로 서로 다른 URL을 정해 등록을 요청하고, 수신 서버에서 URL로 이벤트를 판별해 주세요.

이벤트	등록 URL 예시
지원자 최종 합격	`https://hr.example.com/hooks/ninehire/{토큰}?event=applicant_passed`
지원자 최종 합격 취소	`https://hr.example.com/hooks/ninehire/{토큰}?event=applicant_pass_canceled`
지원자 불합격	`https://hr.example.com/hooks/ninehire/{토큰}?event=applicant_failed`
지원자 불합격 취소	`https://hr.example.com/hooks/ninehire/{토큰}?event=applicant_fail_canceled`
공고 편집	`https://hr.example.com/hooks/ninehire/{토큰}?event=job_posting_updated`
채용 진행 상태 변경	`https://hr.example.com/hooks/ninehire/{토큰}?event=job_status_updated`

5. 이벤트 응답 상세(지원자)

Webhook HTTP Headers

Key	Value
user-agent	ninehire/webhook
content-type	application/json;charset=UTF-8

Response

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

본문에는 이벤트 유형·전송 ID·전송 시각 같은 별도 정보 없이 지원자 객체 자체가 담기며, 지원자 목록 조회 API의 응답 항목과 같은 구조입니다. (회사 정보 company만 제외)

지원자 데이터는 이벤트가 발생한 시점이 아니라 나인하이어가 전송하는 시점의 현재 상태입니다. 예를 들어 지원자 최종 합격 취소 이벤트를 받았을 때 status는 취소 이후의 현재 상태(progressing 등)입니다.

응답 예시

{
  "id": "9f8e7d60-0000-11ef-9000-000000000001",
  "appliedAt": "2026-10-05T03:12:45.120Z",
  "updatedAt": "2026-10-21T01:00:00.000Z",
  "name": "홍길동",
  "email": "[email protected]",
  "phoneNumber": "01000000000",
  "source": "채용홈페이지",
  "status": "passed",
  "recruitment": { "id": "1a2b3c40-0000-11ef-8000-000000000001", "title": "2026 하반기 백엔드 개발자" },
  "step": { "id": "5e6f7a80-0000-11ef-8000-000000000009", "type": "passed", "title": "최종합격" },
  "customAnswers": [
    {
      "title": "이력서",
      "content": null,
      "fileTitle": "홍길동_이력서",
      "fileExtension": "pdf",
      "fileUrl": "https://(나인하이어 파일 도메인)/...pdf?sig=...&version=v0"
    }
  ],
  "educations": [],
  "experiences": [],
  "failReason": null,
  "licenses": [],
  "attachments": [],
  "languages": [],
  "militaryService": null,
  "veteranStatus": null,
  "disability": null,
  "birthday": "1995-03-15",
  "gender": "man",
  "integer": null,
  "address": null,
  "familyRelations": [],
  "computerSkills": [],
  "thesis": []
}

지원자 데이터의 필드 정의와 코드값은 지원자 데이터 정의 가이드에서 확인해 주세요.

✅ 지원자 데이터 정의 사용 가이드 바로가기(클릭)

6. 이벤트 응답 상세 (공고/포지션)

Webhook HTTP Headers

Key	Value
user-agent	ninehire/webhook
content-type	application/json;charset=UTF-8

Response

공고/포지션 웹훅은 이벤트 타입에 상관 없이 모두 동일한 포지션 객체를 전달합니다.

포지션 상세 조회 API(v1)의 국문 응답과 같은 구조입니다. v2 필드(positionStatus, receptionStatus, reception, isListExposed)는 포함되지 않으므로, 필요하면 웹훅을 받은 뒤 포지션 상세 조회 API(v2)로 조회해 주세요.

응답 예시

{
  "id": "1a2b3c40-0000-11ef-8000-000000000001",
  "title": "백엔드 개발자 (경력)",
  "layoutType": "layout1",
  "status": "closed",
  "coverImageUrl": null,
  "applyUrl": "https://example-careers.ninehire.site/job_posting/AbC12dEf",
  "content": "(공고 본문 HTML)",
  "isActive": false,
  "deadline": "2026-10-20T06:30:00.000Z",
  "deadlineType": "custom_deadline",
  "tags": ["개발"],
  "career": "experienced",
  "careerRange": { "over": 3, "below": null },
  "employmentTypes": ["full_time"],
  "jobLocations": [
    { "x": 127.0276, "y": 37.4979, "name": "서울 본사", "address": "서울 본사" }
  ],
  "jobGroup": "개발",
  "jobTask": "백엔드",
  "affiliation": "플랫폼본부",
  "createdAt": "2026-10-01T02:00:00.000Z",
  "isPrivate": true
}

키	타입	비고	설명
id	string		포지션의 고유 ID 값입니다.
title	string		공고 제목(국문)입니다.
layoutType	string		공고 레이아웃 유형입니다. (layout1, layout2)
status	string		포지션 상태입니다.
coverImageUrl	string	nullable	공고 커버 이미지 URL입니다.
applyUrl	string		채용 홈페이지의 공고 페이지 URL입니다.
content	string	nullable	공고 본문(HTML)입니다.
isActive	boolean		공고 사용(게시) 여부입니다. 포지션을 종료하거나 종료를 취소하면 자동으로 false가 됩니다.
deadline	string(datetime)	nullable	접수 마감 일시입니다. 접수를 마감하거나 포지션을 종료하면 처리된 시각이 기록됩니다.
deadlineType	string		마감 방식입니다. 접수 기간이 설정되지 않은 포지션은 open_ended로 표시됩니다.
tags	string[]		태그(국문)입니다.
career	string	nullable	경력 구분입니다.
careerRange	object	nullable	경력 연차 범위입니다. (over: N년 이상, below: N년 이하)
employmentTypes	string[]		고용 형태입니다.
jobLocations	object[]		근무지 목록입니다. (x, y, name, address) address는 근무지 이름과 같은 값입니다.
jobGroup	string	nullable	직군명입니다.
jobTask	string	nullable	직무명입니다.
affiliation	string	nullable	소속명입니다.
createdAt	string(datetime)		포지션 생성 일시입니다.
isPrivate	boolean		채용 홈페이지 목록 미노출 여부입니다. 목록 노출이 꺼져 있으면 true입니다.

status, deadlineType, career, employmentTypes의 코드값은 API 연동 가이드의 5. 포지션 API 응답 객체와 같습니다.

✅ API 연동 사용 가이드 바로가기(클릭)

7. 웹훅 누락 대비

웹훅은 재전송이 없고, 일부 변경(채용 홈페이지 목록 노출 여부, 접수 마감 일시 변경 등)은 웹훅 대상이 아니므로 웹훅만으로 데이터를 빠짐없이 받을 수 없습니다. 아래와 같이 조회 API로 보완해 주세요.

대상	보완 방법
지원자 합격·불합격	진행 중인 포지션별로 지원자 목록 조회(`status=passed&status=failed`)를 주기적으로(예: 1일 1회) 호출해 웹훅 수신 결과와 대조
포지션 상태	포지션 목록 조회(`includeUnpublished=true&includePrivate=true`, v2는 `includeHidden=true`)를 주기적으로 호출해 status·deadline(v2는 reception) 변경 반영
신규 지원자	웹훅 대상이 아니므로 지원자 목록 조회를 주기적으로 호출해 수집

웹훅과 조회 API를 함께 사용할 때는 아래 방식을 권장합니다.

웹훅을 받으면 즉시 2xx로 응답한 뒤 비동기로 처리해 주세요.
받은 지원자 ID(또는 포지션 ID) 기준으로 고객사 데이터를 덮어써 최신 상태로 맞춰 주세요.
정기 배치(예: 1일 1회)로 조회 API를 호출해 웹훅 누락분과 웹훅 대상이 아닌 변경(신규 지원, 채용 홈페이지 목록 노출 여부·접수 마감 일시 변경 등)을 보완해 주세요.
입학일·졸업일 등 날짜 의미의 필드는 UTC+9로 변환한 뒤 날짜를 사용해 주세요.

✅ API 연동 사용 가이드 바로가기(클릭)

✅ 지원자 데이터 정의 사용 가이드 바로가기(클릭)