본문으로 건너뛰기

웹훅

웹훅이란?

웹훅을 사용하면 Hedy가 다른 앱이나 서비스에 실시간으로 데이터를 보낼 수 있습니다. 세션이 종료되거나 주요 내용이 생성되는 등의 이벤트가 발생하면 Hedy가 지정한 URL로 데이터를 보냅니다. 코드를 작성하지 않고도 다양한 작업을 자동화할 수 있습니다.

예를 들어 다음 작업을 자동화할 수 있습니다.

  • 회의 녹취록을 Google Docs 또는 Notion에 저장

  • 세션 요약을 Slack 채널에 게시

  • 실행 항목을 바탕으로 Asana 또는 Todoist에 작업 생성

  • 세션 데이터를 스프레드시트에 기록

웹훅은 이벤트가 발생하면 데이터를 외부로 보냅니다. AI 도우미가 필요할 때 세션 데이터를 가져오도록 하려면 Model Context Protocol(MCP)로 Hedy를 AI 도우미에 연결하는 방법을 참고하세요.

설정한 웹훅은 설정 → 자동화 및 데이터 → API 액세스 → 웹훅 관리에서 확인할 수 있습니다. 각 웹훅에는 구독 중인 이벤트와 생성 날짜가 표시됩니다.

Hedy의 '웹훅' 화면에 설정된 웹훅 3개가 표시됩니다. 각 웹훅의 URL, 구독 중인 이벤트 태그, 생성 날짜를 확인할 수 있습니다.

요구 사항

  • Hedy Pro 구독이 필요합니다. 웹훅은 Pro 기능입니다.

  • 클라우드 동기화 활성화가 필요합니다. Hedy는 클라우드를 통해 웹훅 이벤트를 처리합니다.

클라우드 동기화가 꺼져 있어도 웹훅을 볼 수 있습니다. 웹훅을 만들거나 편집하거나 실행하려면 클라우드 동기화를 활성화하세요.

웹훅 설정

  1. Hedy를 열고 설정으로 이동하세요.

  2. API 액세스 섹션까지 아래로 스크롤하세요.

  3. 웹훅 관리를 누르세요.

  4. + 버튼을 눌러 새 웹훅을 추가하세요.

  5. 이름 (선택 사항)에 웹훅의 용도를 알아볼 수 있는 이름을 입력하세요(예: “Zapier 회의 메모”).

  6. 외부 서비스에서 받은 URL을 웹훅 URL에 붙여넣으세요. HTTPS URL이어야 합니다.

  7. 이벤트에서 구독할 항목을 선택하세요. 선택할 수 있는 이벤트는 아래에 설명되어 있습니다.

  8. 생성을 누르세요.

  9. 웹훅을 만들면 Hedy가 즉시 서명 비밀키를 표시합니다. 이때 한 번만 표시되므로 대화상자를 닫기 전에 복사해 안전한 곳에 보관하세요.

웹훅은 최대 10개까지 만들 수 있습니다.

웹훅 편집

목록에서 웹훅을 누르면 설정 양식이 다시 열립니다. 이름이나 URL 또는 웹훅을 실행할 이벤트를 변경한 뒤 저장을 누르세요.

Hedy의 '웹훅 편집' 대화상자입니다. 이름과 URL 입력란 아래에 구독할 수 있는 이벤트 목록이 있으며 session.ended가 선택되어 있습니다.

웹훅을 편집해도 서명 비밀키는 바뀌지 않습니다. Hedy는 웹훅을 처음 만들 때 한 번만 서명 비밀키를 발급합니다.

사용 가능한 이벤트

웹훅을 실행할 이벤트를 선택하세요.

세션 생성 (session.created)은 새 세션을 시작할 때 발생합니다. 세션 제목과 시작 시각을 보냅니다.

세션 종료 (session.ended)는 세션이 끝날 때 발생합니다. 녹취록, 요약, 회의록, 주요 내용, 직접 작성한 세션 노트, 토픽 정보를 포함한 전체 세션 데이터를 보냅니다. 가장 많은 데이터를 보내는 이벤트입니다.

세션 내보내기 (session.exported)는 세션을 웹훅으로 수동으로 내보낼 때 발생합니다. 세션 종료 이벤트와 비슷한 데이터(녹취록, 요약, 주요 내용, 세션 노트 등)를 보냅니다.

주요 내용 생성 (highlight.created)은 세션 중에 주요 내용을 캡처할 때마다 발생합니다. 주요 내용의 텍스트, AI 인사이트, 타임스탬프를 보냅니다.

제안 생성 (suggestion.created)은 실시간 세션 중에 Hedy가 자동 제안을 표시할 때마다 발생합니다. 제안 텍스트, 해당 세션, 세션 유형을 보냅니다. Hedy는 한 세션에서 여러 제안을 표시할 수 있으므로 이 이벤트는 다른 이벤트보다 자주 발생할 수 있습니다.

할 일 내보내기 (todo.exported)는 실행 항목을 내보낼 때 발생합니다. 할 일의 텍스트, 마감일, 관련 세션을 보냅니다.

세션 수동 내보내기

이벤트에 따른 자동 전송 외에도 원하는 세션을 웹훅으로 직접 보낼 수 있습니다.

  1. 완료된 세션을 여세요.

  2. 웹훅으로 내보내기를 누르세요.

  3. 세션 내보내기(session.exported) 이벤트를 구독하는 웹훅이 여러 개라면 전송할 웹훅을 선택하세요.

  4. 내보내기를 확인하세요.

웹훅 테스트

웹훅을 사용하기 전에 정상적으로 작동하는지 확인할 수 있습니다.

  1. 설정 → 자동화 및 데이터 → API 액세스 → 웹훅 관리로 이동하세요.

  2. 확인할 웹훅의 웹훅 테스트 버튼을 누르세요.

  3. Hedy가 지정한 URL로 테스트 페이로드를 보내고 성공 여부와 응답 상태 코드를 표시합니다.

테스트에 실패하면 URL이 올바른지, 외부 서비스가 요청을 받을 준비가 되었는지 다시 확인하세요.

webhook.site에서 페이로드 확인

Zapier나 Make 또는 자체 서버를 연결하기 전에 Hedy가 보내는 모든 헤더와 전체 JSON 본문, 서명을 확인하려면 webhook.site를 이용하는 것이 가장 빠릅니다.

  1. webhook.site를 여세요. 가입 없이 고유 URL이 즉시 생성됩니다.

  2. URL을 복사해 Hedy의 웹훅에 붙여넣으세요.

  3. Hedy에서 웹훅 테스트를 누르거나 실제 이벤트를 발생시키세요.

  4. webhook.site로 돌아가세요. 모든 요청이 실시간으로 표시되며, 각 요청의 전체 헤더, 쿼리 문자열, 본문을 확인할 수 있습니다.

이 방법으로 Hedy가 보내는 페이로드의 정확한 필드 이름과 구조를 확인한 뒤 그 형식에 맞춰 실제 자동화를 구성하세요. 무료 요금제는 URL당 최대 100개 요청을 받을 수 있어 문제를 점검하기에 충분합니다.

전송되는 데이터

모든 웹훅 요청은 JSON 본문을 담은 HTTP POST입니다. 전송되는 데이터는 이벤트 유형에 따라 다릅니다. 세션 종료(session.ended) 이벤트에는 다음 데이터가 포함됩니다.

  • 세션 세부 정보에는 제목, 시작 시각, 종료 시각, 세션 길이가 포함됩니다.

  • 녹취록에는 세션의 전체 텍스트가 담깁니다.

  • 대화는 화자별로 정리된 대화 내용입니다.

  • 회의록에는 주요 논의 사항이 담깁니다.

  • 요약은 AI가 생성합니다.

  • 주요 내용에는 각 항목의 AI 인사이트, 인용문, 타임스탬프가 포함됩니다.

  • 세션 노트는 직접 작성한 메모로, session_notes 필드에 들어갑니다. 서식 있는 텍스트를 담은 JSON이며, 작성한 메모가 없으면 빈 문자열입니다. Hedy 3.4 이상에서는 session.ended 및 session.exported 이벤트에 포함됩니다.

  • 토픽에는 세션이 속한 토픽의 이름과 토픽 인사이트가 포함됩니다.

세션 노트 참고 사항. 세션 종료 후 몇 초 이내에 종료 화면에서 입력한 메모는 Hedy가 아직 저장 중이어서 첫 session.ended 전송에 포함되지 않을 수 있습니다. 해당 메모는 session.exported와 API에 항상 포함되므로 필요한 경우 세션을 다시 내보내세요.

suggestion.created 이벤트는 훨씬 적은 데이터를 보냅니다. 제안 텍스트, 제안 식별자, 해당 세션, 세션 유형, 타임스탬프만 포함됩니다. 이 이벤트가 도착할 때 세션이 아직 진행 중일 수 있으므로 전체 녹취록과 요약이 필요하면 session.ended를 사용하세요.

보안 및 검증

모든 웹훅 요청에는 Hedy에서 보낸 요청인지 확인할 수 있는 서명이 포함됩니다.

  • X-Hedy-Signature 헤더에는 웹훅 고유의 서명 비밀키로 요청 본문에 대해 계산한 HMAC-SHA256 해시가 16진수로 들어갑니다. sha256= 접두사는 붙지 않습니다. 서명 비밀키는 웹훅을 만들 때 한 번만 표시됩니다.

  • X-Hedy-Event 헤더에는 이벤트 유형(예: session.ended)이 들어갑니다.

전송 중에 데이터를 암호화하려면 모든 웹훅 URL에 HTTPS를 사용해야 합니다. Hedy는 HTTP 엔드포인트로 데이터를 보내지 않습니다.

서명 검증

자체 엔드포인트를 구축한다면 모든 요청을 검증한 뒤 처리하세요. 서명 비밀키를 사용해 원본 요청 본문의 HMAC-SHA256 해시를 계산하고, 상수 시간 비교로 X-Hedy-Signature 헤더 값과 비교하세요. 일반적인 == 비교는 타이밍 공격에 취약합니다.

Node.js:

const crypto = require('crypto');

function verifyHedy(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(signature, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hmac, hashlib

def verify_hedy(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

중요. 요청 본문은 원본 바이트를 수신한 그대로 사용하세요. 파싱한 JSON을 다시 직렬화하면 공백이나 키 순서가 바뀌어 서명이 일치하지 않습니다.

주요 플랫폼에서 웹훅 사용

Zapier에서 “Webhooks by Zapier”를 트리거로 사용하는 Zap을 만드세요. “Catch Hook”을 선택하고 웹훅 URL을 복사해 Hedy에 붙여넣으세요.

Make(이전 이름 Integromat)에서 시나리오 트리거로 “Custom Webhook” 모듈을 추가하세요. 생성된 URL을 복사해 Hedy에 붙여넣으세요. Make용 Hedy 앱을 사용할 수도 있습니다. 이 앱의 “Watch events” 트리거가 웹훅을 등록하므로 URL을 복사할 필요가 없습니다.

n8n에서 워크플로에 “Webhook” 트리거 노드를 추가하세요. 운영용 URL을 복사해 Hedy에 붙여넣으세요.

전송 및 재시도

Hedy는 전송에 실패하면 자동으로 재시도합니다.

  • 서버 오류(5xx)가 발생하면 재시도 간격을 늘리면서 최대 2회 재시도합니다.

  • 요청 횟수 제한(429)에 걸리면 서비스가 지정한 대기 시간을 지켜 한 번 재시도합니다.

  • 클라이언트 오류(4xx)는 대개 설정 문제를 나타내므로 재시도하지 않습니다.

엔드포인트 응답 요건. 5초 이내에 2xx 상태 코드로 응답하세요. 200 OK로 응답해도 됩니다. 응답 본문은 무시됩니다. 데이터베이스에 저장하거나 다른 API를 호출하거나 문서를 생성하는 등 시간이 걸리는 작업이 있다면 즉시 200을 반환하고 페이로드를 비동기로 처리하세요. 응답이 늦으면 Hedy에서 시간 초과가 발생해 전송이 실패로 표시됩니다.

문제 해결

Hedy에서 발생하는 문제

“웹훅은 Pro가 필요합니다” 메시지가 표시되면 설정 → 계정 → 내 요금제에서 Hedy Pro로 업그레이드하세요.

“클라우드 동기화 필요” 메시지가 표시되면 설정 → 개인 정보 및 시스템 → 개인정보 보호 기본 설정 → 클라우드 동기화에서 클라우드 동기화를 켜거나, ‘웹훅’ 화면 상단의 경고 배너에서 활성화 버튼을 누르세요.

이벤트가 수신되지 않으면 클라우드 동기화가 켜져 있는지, 웹훅이 올바른 이벤트를 구독하는지, Pro 구독이 활성 상태인지 확인하세요.

전송 문제

테스트에 실패하거나 이벤트가 도착하지 않으면 웹훅의 대상을 webhook.site로 바꿔 다시 테스트하는 것이 문제의 원인을 파악하는 가장 빠른 방법입니다. 그곳에 요청이 표시되면 Hedy는 정상적으로 전송하고 있으며, 문제는 수신 측에 있습니다.

시간 초과로 테스트 실패. 엔드포인트는 테스트 요청에 10초 이내, 실제 이벤트 요청에 5초 이내로 응답해야 합니다. 데이터베이스에 저장하거나 다른 API를 호출하거나 PDF를 생성하는 등 시간이 걸리는 작업을 응답 전에 처리하고 있다면, 즉시 200 OK를 반환하고 페이로드를 비동기로 처리하세요.

SSL 또는 인증서 오류. 엔드포인트의 HTTPS 인증서가 만료되었거나 자체 서명된 인증서를 사용 중이거나 중간 인증서가 누락된 경우입니다. SSL Labs에서 점검한 뒤 인증서를 갱신하거나 인증서 체인을 수정하세요.

연결 거부 또는 404 오류. URL이 잘못되었거나 경로가 존재하지 않거나 서버가 실행 중이 아닌 경우입니다. 먼저 webhook.site로 테스트 요청을 보낸 뒤 URL을 비교해 정확한 주소를 확인하세요.

Zap 또는 Make 시나리오에서 “404 not found” 오류. 워크플로가 일시 중지되었거나 초안 상태이거나 테스트 URL을 사용하고 있을 수 있습니다. Zapier에서 Zap은 On 상태여야 합니다. Make에서 시나리오는 Active 상태여야 합니다. n8n에서는 Production URL을 사용하세요. Test URL은 테스트용입니다.

요청이 별다른 오류 없이 차단되는 경우. 방화벽, WAF 또는 보안 플러그인(Wordfence, Sucuri, Cloudflare의 봇 차단 기능)이 들어오는 POST 요청을 차단하고 있습니다. 서버의 액세스 로그를 확인하세요. Hedy의 요청이 전혀 기록되지 않으면 Hedy 또는 Hedy가 보내는 User-Agent를 허용 목록에 추가하세요.

서명이 일치하지 않는 경우. 원본 요청 본문 바이트 대신 파싱하거나 다시 직렬화한 JSON으로 서명을 검증하고 있거나, 비교하는 값 앞에 sha256=를 붙인 경우입니다. Hedy의 서명에는 이 접두사가 없습니다. 위의 “서명 검증”을 참고하세요.

활용 팁. 먼저 세션 종료 (session.ended) 이벤트를 구독하세요. 이 이벤트는 가장 많은 데이터를 담고 있어 회의 메모를 활용한 자동화를 만들 때 가장 유용합니다.