웹훅을 사용하면 변경이 발생하는 즉시 AgencyHandy가 외부 시스템으로 데이터를 전송할 수 있습니다 — 폴링이 필요하지 않습니다. 설정된 이벤트가 발생하면(예: 주문 업데이트 또는 티켓 생성), AgencyHandy는 지정한 엔드포인트 URL로 JSON 페이로드가 포함된 HTTP POST 요청을 전송합니다. 이를 통해 CRM, 청구 시스템, 또는 맞춤형 대시보드 같은 외부 도구를 AgencyHandy 워크스페이스와 실시간으로 동기화하는 것이 간편해집니다.
Business Pro 플랜 워크스페이스는 청구 기간당 최대 30,000건의 웹훅 이벤트를 지원합니다. 대용량 자동화를 설정하기 전에 플랜 한도를 확인하세요.
지원 이벤트
웹훅은 다음 이벤트의 임의 조합을 구독할 수 있습니다:
| 카테고리 | 이벤트 |
|---|
| 서비스 | 생성, 업데이트, 삭제 |
| 주문 | 생성, 업데이트, 삭제 |
| 태스크 | 생성, 배정, 완료, 업데이트 |
| 인보이스 | 상태 변경 |
| 클라이언트 / 사용자 | 새 클라이언트 추가, 클라이언트/사용자 삭제 |
| 제안서 | 전송, 수신, 수락, 거절 |
| 티켓 | 생성, 배정, 상태 변경 |
| 결제 | 수신, 실패 |
| 서비스 패키지 | 생성, 업데이트, 삭제 |
웹훅 생성
웹훅 관리로 이동
왼쪽 사이드바에서 연동 → 웹훅 관리로 이동합니다.
토큰 인증
관리 버튼을 클릭하여 웹훅 토큰을 인증합니다. 이 토큰은 발신 페이로드에 서명하는 데 사용되므로 AgencyHandy에서 생성된 것임을 검증할 수 있습니다.
새 웹훅 생성
새 웹훅 생성을 클릭하여 웹훅 설정 양식을 엽니다.
엔드포인트 URL 입력
엔드포인트 URL 필드에 웹훅 데이터를 수신해야 하는 외부 시스템의 URL을 입력합니다. 공개적으로 접근 가능한 POST 엔드포인트여야 합니다.
콘텐츠 유형 선택
콘텐츠 유형으로 JSON을 선택합니다. AgencyHandy는 모든 웹훅 페이로드를 application/json으로 전송합니다.
웹훅 이벤트 선택
이 웹훅을 트리거해야 하는 모든 이벤트를 선택합니다. 여러 카테고리의 이벤트를 선택할 수 있습니다 — 예를 들어, 주문: 생성과 인보이스: 상태 변경 모두 같은 엔드포인트를 가리킬 수 있습니다.
웹훅 활성화
활성 라디오 버튼을 토글합니다. 활성화되면 AgencyHandy는 선택된 모든 이벤트에 대한 페이로드를 실시간으로 엔드포인트에 전달합니다.
설정 저장
설정을 검토한 후 저장을 클릭합니다. 웹훅이 목록에 나타나고 즉시 이벤트 전달을 시작합니다.
웹훅 테스트
웹훅을 생성한 후, 엔드포인트에 접근 가능하고 데이터를 올바르게 처리하는지 확인하기 위해 테스트 페이로드를 전송합니다.
웹훅 열기
웹훅 관리 목록에서 테스트할 웹훅을 클릭합니다.
테스트 이벤트 클릭
웹훅 상세 페이지에서 테스트 이벤트 버튼을 클릭합니다.
테스트 이벤트 선택
이 웹훅에 설정된 이벤트 목록에서 샘플 이벤트를 선택합니다(예: 주문: 생성).
테스트 페이로드 전송
전송을 클릭합니다. AgencyHandy가 엔드포인트 URL로 샘플 페이로드를 게시합니다.
결과 확인
외부 시스템에서 테스트 페이로드가 도착하여 예상대로 처리되었는지 확인합니다. AgencyHandy로 돌아가 웹훅을 클릭하여 내역을 검토합니다 — 전체 요청, 엔드포인트가 반환한 응답을 확인하고, 필요한 경우 과거 이벤트를 재전달할 수 있습니다.
웹훅 페이로드 인증
AgencyHandy의 모든 발신 웹훅 요청에는 엔드포인트가 페이로드의 진위 여부와 변조 여부를 확인하는 데 사용할 수 있는 서명 헤더가 포함됩니다.
서명 헤더
AgencyHandy는 모든 웹훅 요청에 이 헤더를 추가합니다. 수신 요청에서 값을 추출하여 검증 엔드포인트에 전달합니다.
웹훅 서명 검증
페이로드가 진본임을 확인하려면 다음 요청을 전송합니다:
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
이벤트를 수신한 웹훅의 ID입니다. AgencyHandy의 웹훅 상세 페이지에서 확인할 수 있습니다.
수신 웹훅 요청의 x-ah-sig 헤더 값입니다.
AgencyHandy의 웹훅 상세 페이지에 표시된 웹훅 시크릿입니다.
AgencyHandy 웹훅 요청으로부터 수신한 원시 JSON 본문입니다.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';
const postData = {
webhookId: 'your_webhook_id',
signature: 'your_signature', // value of x-ah-sig header
secret: 'your_webhook_secret',
payload: {}, // the parsed JSON body from AgencyHandy
};
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(postData),
});
const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
서명이 유효하면 SUCCESS. 검증 실패 시 FAILED (HTTP 403).
{
"verification_status": "SUCCESS"
}
{
"type": "PermissionError",
"status": 403,
"verification_status": "FAILED"
}
웹훅 시크릿을 기밀로 유지하세요. 정기적으로 교체하고 교체 직후 검증 로직을 업데이트하세요. 클라이언트 측 코드나 공개 저장소에 절대 노출하지 마세요.
중요 참고 사항
- 엔드포인트 URL은 공개적으로 접근 가능한 HTTPS POST URL이어야 합니다.
- 엔드포인트가 일시적으로 사용 불가능한 경우, AgencyHandy에서 웹훅의 내역 패널을 확인하세요 — 거기서 직접 과거 이벤트를 재전달할 수 있습니다.
- 실패한 전달이나 무단 접근 시도를 감지하려면 웹훅 활동을 정기적으로 모니터링하세요.
- 반복적으로 실패하는 웹훅은 AgencyHandy에 의해 일시 중지될 수 있습니다 — 조기에 문제를 파악하려면 전달 로그를 검토하세요.
