AuraDoc
로그인가입

블로그

AuraDoc의 웹훅과 REST API

범위가 있는 API 키, 서명된 웹훅, 전달 기록, 자동 재시도로 AuraDoc을 자사 시스템과 연결하세요.


대부분의 팀은 언젠가 문서가 다른 소프트웨어와 연동되기를 원합니다. 스크립트로 파일을 올리거나, 스케줄러에서 워크플로를 시작하거나, 문서 처리가 끝나는 순간 알림을 받고 싶어집니다. AuraDoc은 서로 보완하는 두 가지 방법을 제공합니다. REST API는 자사 시스템이 AuraDoc에 무언가를 요청하게 하고, 웹훅은 AuraDoc이 자사 시스템에 어떤 일이 일어났음을 알리게 합니다. 이 글에서는 두 가지와 운영 환경에서 중요한 보안 사항을 살펴봅니다.

API 키와 범위

모든 것은 API 키에서 시작합니다. Dashboard › Settings › API keys에서 키를 만들고 이름을 정한 뒤 범위를 선택하세요. 범위는 키가 할 수 있는 일을 제한하므로, 파일 업로드에만 쓰는 키에는 다른 것을 관리할 권한이 필요 없습니다. 키는 자신보다 넓은 범위를 가진 다른 키를 만들 수 없고, 실제 권한은 항상 키와 해당 사람의 역할이 공통으로 가진 권한입니다. 자세한 내용은 팀 역할과 권한을 보세요. 요청은 Authorization 헤더에 Bearer 토큰으로 키를 담아 보냅니다.

같은 페이지에서 키별 사용 통계를 볼 수 있어 어떤 연동이 활발하고 어떤 연동이 조용해졌는지 알 수 있습니다. 유료 요금제에서는 개별 키에 요청 제한을 설정할 수도 있어, 요청이 많은 스크립트 하나가 다른 스크립트에 영향을 주지 않게 할 수 있습니다. 키가 유출되면 삭제하고 새로 만드세요. AuraDoc 쪽에서는 다른 것을 바꿀 필요가 없습니다.

API로 할 수 있는 일

문서의 연동 페이지에는 기본 주소와 바로 복사해 쓸 수 있는 예시가 있습니다. 현재 문서 업로드, URL에서 문서 가져오기, 워크플로 실행 시작, 서명 요청 생성을 각각 인증된 요청 한 번으로 할 수 있습니다. 대시보드에서 사람이 하는 작업과 같은 동작이므로, API로 만든 결과도 다른 결과처럼 화면에 나타납니다.

호출을 받기보다 직접 조회하고 싶다면, 새 문서, 완료된 워크플로 실행, 완료된 서명을 돌려주는 트리거 엔드포인트와 이를 설명하는 카탈로그가 있습니다. 스프레드시트 애드온이나 노코드 플랫폼처럼 웹훅을 받을 수 없는 도구는 이 엔드포인트를 주기적으로 조회할 수 있습니다. 전체 참조는 연동 문서 페이지에 있습니다.

발신 웹훅

실시간 알림이 필요하면 Dashboard › Webhooks를 열어 엔드포인트를 추가하세요. 문서 생성, 분류, 삭제, OCR과 번역의 완료 또는 실패, 워크플로 이벤트, 저장 용량 경고, 서명 관련 이벤트 등 필요한 이벤트를 목록에서 고릅니다. 저장하면 AuraDoc이 서명 비밀 값을 한 번만 보여 줍니다. 곧바로 수신 서비스에 복사하세요. 잃어버렸다면 비밀 값을 교체하면 새 값이 만들어지고, 교체 기록이 감사 로그에 남습니다.

페이로드는 수천 자까지의 템플릿으로 다듬을 수 있으며 저장 전에 검증할 수 있습니다. 테스트 버튼은 테스트 헤더가 붙은 샘플 이벤트를 보내, 의존하기 전에 엔드포인트에 연결되고 본문을 읽는지 확인하게 해 줍니다. 각 웹훅은 삭제하지 않고 끌 수 있어 점검 시간에 유용합니다.

서명 검증과 장애 처리

모든 전달에는 서명이 붙습니다. AuraDoc은 비밀 값으로 타임스탬프와 원본 본문에 대한 HMAC-SHA256을 계산해 서명 헤더로 보내며, 이벤트 이름, 웹훅 ID, 전달 ID, 타임스탬프, 재시도 횟수 헤더도 함께 보냅니다. 수신자는 원본 본문으로 서명을 다시 계산하고, 일정한 시간으로 비교하며, 타임스탬프가 너무 오래된 요청은 거부해야 합니다. 이렇게 하면 주소를 알더라도 아무도 엔드포인트로 이벤트를 위조할 수 없습니다.

엔드포인트는 멈출 수 있고 AuraDoc은 이에 대비합니다. 전달이 실패하면 5분에서 6시간까지 간격을 늘려 가며 자동으로 재시도합니다. 전달 보기에서 모든 시도와 결과를 볼 수 있고, 문제를 고친 뒤 수동으로 재시도할 수도 있습니다. 재시도에는 같은 전달 ID가 쓰이므로 수신자는 중복을 안전하게 무시할 수 있습니다. 저장소 제공업체에서 들어오는 파일과 웹훅을 함께 쓰는 방법은 클라우드 스토리지와 감시 폴더를 참고하세요.

블로그로 돌아가기