Webhooks 개요

등록·검증·식별 작업의 결과를 폴링 없이, 서명된 HTTPS 이벤트로 고객사 서버에서 받는 방법

Webhooks란?

등록, 검증, 식별은 비동기 작업입니다. Webhooks를 쓰지 않으면 고객사 서버가 작업 상태가 PENDING에서 바뀔 때까지 폴링해야 합니다. Webhooks를 쓰면 작업이 끝나는 시점에 Petify가 고객사 서버로 서명된 HTTPS POST 요청을 한 번 보내고, 요청 본문에 결과가 담겨 있습니다.

Webhooks는 모든 플랜에서 사용할 수 있습니다. Petify Console에서 직접 설정합니다.

Webhooks는 작업 조회 엔드포인트를 대체하지 않습니다. 작업 상태의 기준은 계속 폴링 엔드포인트(GET /v2/.../jobs/{jobId})입니다. 결과를 더 빨리 받으려고 Webhooks를 쓰고, 놓친 이벤트는 폴링으로 복구하세요. 전송과 재시도를 참고하세요.

호스팅 세션(hosted session)이 만든 작업은 현재 Webhook 이벤트를 보내지 않습니다. Web Integration(링크 연동·서버 연동)의 세션은 리다이렉트와 결과 코드로 완료를 전달합니다. Webhooks는 Server API로 직접 만든 작업에 적용됩니다.

동작 방식

고객사 서버가 기존처럼 API로 작업을 시작합니다.
작업이 SUCCESS 또는 FAILED가 되면, Petify가 해당 이벤트 유형을 구독하고 사용 중인 모든 엔드포인트로 이벤트를 보냅니다.
엔드포인트는 서명을 검증하고 이벤트를 처리한 뒤 2xx 상태로 응답합니다.
2xx로 응답하지 않으면 Petify가 정해진 일정에 따라 재시도합니다.

Console에서 빠르게 시작하기

POST 요청과 JSON 본문을 받는 HTTPS 엔드포인트를 만듭니다. 서명 검증 예제에서 시작하면 편합니다.
Petify Console에서 Integration을 열고 Webhooks 탭을 선택합니다.
엔드포인트 추가를 클릭합니다.
엔드포인트 URL을 입력합니다. 설명은 선택 사항이며 200자까지 입력할 수 있습니다.
이벤트에서 받을 이벤트 유형을 고르거나 **모든 이벤트 (나중에 추가되는 이벤트 포함)**를 선택합니다. 하나 이상 선택해야 합니다.
엔드포인트 추가를 클릭해 저장합니다. 대화상자에 서명 시크릿(whsec_...)이 한 번 표시됩니다. 복사해서 시크릿 매니저 등에 안전하게 보관하세요.
엔드포인트를 열고 테스트 이벤트 보내기를 클릭합니다. Petify가 서명된 webhook.test 이벤트를 한 번 보내고, 엔드포인트가 2xx로 응답했는지 보여 줍니다.

서명 시크릿은 언제든 다시 확인할 수 있습니다. 엔드포인트를 열고 시크릿 보기를 클릭하세요.

Console의 이벤트 선택 화면은 이벤트를 등록, 인증, 검색 그룹으로 나눕니다. 이 문서의 검증(verification)이 인증, 식별(identification)이 검색입니다.

엔드포인트 관리

작업	설명
엔드포인트 추가	새 서명 시크릿과 함께, 사용 중 상태의 엔드포인트를 만듭니다.
수정	URL, 설명, 구독 이벤트를 바꿉니다. 서명 시크릿은 그대로입니다. 구독 변경은 저장 이후에 발생하는 이벤트부터 적용됩니다.
사용 스위치	엔드포인트를 켜거나 끕니다. 꺼져 있는 동안 해당 이벤트는 건너뜀으로 기록되고 전송되지 않습니다. 사용 중지된 엔드포인트를 참고하세요.
시크릿 보기 / 시크릿 교체	현재 서명 시크릿을 보여 주거나 새 시크릿을 만듭니다. 교체 후 이전 시크릿은 24시간 동안 계속 서명에 쓰입니다. 시크릿 교체를 참고하세요.
테스트 이벤트 보내기	서명된 `webhook.test` 이벤트를 지금 한 번 보냅니다. 엔드포인트가 사용 중지 상태여도 전송되며, 재시도하지 않고 전송 로그에도 남기지 않습니다.
삭제	엔드포인트와 전송 로그를 삭제합니다. 되돌릴 수 없습니다.

엔드포인트 요건과 제한

항목	규칙
URL 스킴	`https`만 사용할 수 있습니다.
호스트	공용 인터넷에서 접근할 수 있어야 합니다. 사설·로컬 주소(예: `localhost`, `10.x.x.x`)는 등록할 수 없습니다.
URL 길이	최대 500자
설명	선택 사항, 최대 200자
계정당 엔드포인트	최대 5개. 추가하려면 하나를 삭제하세요.
리다이렉트	따라가지 않습니다. `3xx` 응답은 실패한 시도로 처리됩니다.
응답 시간	10초 이내에 응답해야 합니다.
요청 헤더	`User-Agent: Petify-Webhooks/1`, 그리고 서명 헤더

여러 엔드포인트가 같은 이벤트 유형을 구독하면, 각 엔드포인트가 같은 본문과 같은 webhook-id로 이벤트를 받습니다.

다음 단계

이벤트와 페이로드 - 이벤트 유형과 본문 예시
서명 검증 - Node.js·Python 코드 예제
전송과 재시도 - 재시도 일정, 중복 처리, 재전송, 전송 로그