Callabo Webhook 가이드: 미팅 전사·인사이트 payload 연동하기

Callabo Webhook으로 처리 완료된 미팅의 전사, 인사이트와 메타데이터를 수신하는 방법을 안내합니다. endpoint 조건, secret 검증, payload schema, 테스트와 재시도 정책을 확인하세요.

jelly

Aug 21, 2026

Callabo Webhook 가이드: 미팅 전사·인사이트 payload 연동하기

Contents

Webhook 동작과 전송 범위 수신 endpoint와 인증 요구사항 Callabo webhook payload schema owner와 event dialogs와 teams webhook payload 예시 sample payload와 실제 레코드 테스트하기 재시도와 중복 처리 정책 운영 체크리스트

Callabo Webhook을 사용하면 미팅 처리가 완료됐을 때 전사, AI 인사이트, 일정과 미팅 메타데이터를 지정한 endpoint로 받을 수 있습니다. Callabo는 JSON payload를 HTTP POST로 전송하며, 워크스페이스 Webhook과 팀 Webhook은 같은 payload schema를 사용합니다.

현재 Webhook은 일반 연동 화면에서 지원 예정으로 표시되며 모든 워크스페이스에 셀프서비스로 열려 있지 않습니다. 서버 플랜 기준으로 Team·Business 플랜에 Webhook 기능이 포함되지만, 실제 사용에는 워크스페이스별 활성화와 설정이 필요할 수 있습니다. 도입 전에 Callabo 채널톡 또는 담당자에게 사용 가능 여부, 전송 범위와 endpoint 등록 방법을 확인하세요.

Webhook 동작과 전송 범위

Callabo는 레코드의 전사와 후처리가 끝나 processed 상태가 되면 등록된 Webhook을 호출합니다.

워크스페이스 Webhook은 설정된 scope와 레코드의 공개 범위가 일치할 때 전송합니다.
팀 Webhook은 레코드에 연결된 팀의 Webhook 중 설정된 scope와 일치하는 대상에 전송합니다.
하나의 레코드가 여러 팀에 연결돼 있고 각 팀에 endpoint가 있다면 여러 곳으로 전송될 수 있습니다.
재전사나 재처리로 새 처리 세대가 만들어지면 같은 id의 갱신된 payload가 다시 전송될 수 있습니다.
워크스페이스의 Webhook 개인정보 마스킹 정책이 켜져 있으면 제목, 사용자, 전화번호, 대화와 인사이트 일부가 마스킹될 수 있습니다.

scope는 workspace, team, private 중 하나입니다. 실제로 어떤 범위를 외부 시스템에 보낼지는 워크스페이스의 미팅 접근 정책과 함께 설계하세요. 미팅 공개 범위는 미팅 관리 가이드를 참고할 수 있습니다.

수신 endpoint와 인증 요구사항

운영 endpoint는 다음 조건을 만족해야 합니다.

공개 인터넷에서 접근 가능한 https URL을 사용합니다. http도 schema상 허용되지만 운영 환경에서는 사용하지 마세요.
localhost, .localhost, 사설·loopback·link-local·예약 IP로 해석되는 주소는 사용할 수 없습니다.
redirect를 따라가지 않으므로 최종 처리 URL을 직접 등록합니다.
한 번의 요청은 10초 안에 끝나야 합니다.
HTTP 200 이상 300 미만을 반환하면 성공입니다. 응답 body는 일반 전송의 성공 판정에 사용하지 않습니다.
payload가 크거나 후처리가 오래 걸리면 요청을 검증해 queue에 넣고 즉시 200 또는 204를 반환합니다.

Webhook secret을 설정하면 Callabo는 다음 header를 보냅니다.

Content-Type: application/json
x-webhook-secret: <등록한 secret>

x-webhook-secret은 HMAC 서명이나 일회성 token이 아니라 등록할 때 정한 고정 secret입니다. 수신 서버는 HTTPS를 사용하고, 환경 변수나 secret manager에 저장한 값과 header를 비교해야 합니다. 현재 payload에는 전송 시각, 서명 또는 외부용 delivery ID가 없으므로 이를 HMAC 검증처럼 해석하면 안 됩니다.

다음 Node.js 예시는 secret을 확인하고 무거운 처리를 queue로 넘기는 최소 구조입니다.

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json({ limit: "20mb" }));

app.post("/webhooks/callabo", async (req, res) => {
  const expected = Buffer.from(process.env.CALLABO_WEBHOOK_SECRET ?? "");
  const received = Buffer.from(req.get("x-webhook-secret") ?? "");
  const authenticated =
    expected.length > 0 &&
    expected.length === received.length &&
    crypto.timingSafeEqual(expected, received);

  if (!authenticated) return res.sendStatus(401);
  if (!Number.isInteger(req.body?.id)) return res.sendStatus(400);

  const bodyHash = crypto
    .createHash("sha256")
    .update(JSON.stringify(req.body))
    .digest("hex");

  await enqueueCallaboWebhook({
    recordId: req.body.id,
    bodyHash,
    payload: req.body,
  });
  return res.sendStatus(204);
});

secret이나 전체 payload를 application log에 남기지 마세요. 유출이 의심되면 새 secret으로 endpoint 설정을 교체하고 기존 값을 폐기합니다.

Callabo webhook payload schema

최상위 JSON은 다음 필드를 포함합니다.

필드	타입	nullable	설명
`id`	integer	아니요	Callabo 레코드 ID
`source`	string enum	아니요	녹음·녹화 출처
`owner`	object	예	레코드 소유자
`event`	object	예	연결된 캘린더 일정
`title`	string	아니요	미팅 제목
`duration`	number	예	미팅 길이, 초 단위·최대 소수점 셋째 자리
`start_date`	ISO 8601 datetime	아니요	`rec_date - duration`; duration이 없으면 `rec_date`
`created_at`	ISO 8601 datetime	아니요	Callabo 레코드 생성 시각
`rec_date`	ISO 8601 datetime	아니요	녹음·녹화 종료 시각
`filesize`	integer	아니요	원본 파일 크기, byte
`dialogs`	array	아니요	화자별 발화 목록
`teams`	array	아니요	레코드에 연결된 팀 목록
`scope`	string enum	아니요	`workspace`, `team`, `private`
`phone_number`	string	예	`phone_call` 출처의 상대 전화번호, E.164 형식
`insight_markdown`	string	예	AI 인사이트를 Markdown으로 직렬화한 값
`link`	string	예	Callabo 미팅 상세 링크
`transcript`	string	아니요	`dialogs[].msg`를 줄바꿈으로 합친 전체 대화록

source는 다음 값 중 하나입니다.

zoom
google_meet
teams_meet
phone_call
voice_recorder
screen_recorder
video_recorder
manual_upload

owner와 event

owner는 레코드 소유자가 있을 때 email, name을 포함합니다. 캘린더 일정이 연결된 event는 다음 필드를 가집니다.

필드	타입	설명
`summary`	string	일정 제목
`start`	ISO 8601 datetime	일정 시작 시각
`end`	ISO 8601 datetime	일정 종료 시각
`attendees`	array	참석자의 `email`, `displayName` 목록
`conference_url`	string	온라인 미팅 URL
`recurring`	boolean	반복 일정 여부

일정이 없는 녹음이나 업로드는 event가 null일 수 있습니다. 참석자 이메일이 없는 event attendee는 payload 목록에서 제외됩니다.

dialogs와 teams

dialogs[]는 start_at, duration, msg, speaker를 포함합니다. 두 시간 값은 레코드 시작을 기준으로 한 초 단위 숫자이며 최대 소수점 셋째 자리로 직렬화됩니다. speaker는 화자 번호이고, 화자 이름이 아닙니다.

teams[]는 name과 선택적인 email을 포함합니다. 전체 대화 문자열이 필요하면 transcript를, 화자와 시각이 필요한 처리는 dialogs를 사용하세요.

webhook payload 예시

아래는 필드를 줄인 Zoom 예시입니다.

{
  "id": 60234,
  "source": "zoom",
  "owner": {
    "email": "ceo@example.com",
    "name": "김대표"
  },
  "event": {
    "summary": "분기 전략 회의",
    "start": "2026-08-18T09:00:00+09:00",
    "end": "2026-08-18T10:00:00+09:00",
    "attendees": [
      {
        "email": "pm@example.com",
        "displayName": "박프로덕트"
      }
    ],
    "conference_url": "https://zoom.us/j/123456789",
    "recurring": false
  },
  "title": "제품 전략 회의",
  "duration": 3600.0,
  "start_date": "2026-08-18T09:00:00+09:00",
  "created_at": "2026-08-18T09:05:00+09:00",
  "rec_date": "2026-08-18T10:00:00+09:00",
  "filesize": 73400320,
  "dialogs": [
    {
      "start_at": 0.0,
      "duration": 15.2,
      "msg": "오늘은 제품 출시 일정을 점검하겠습니다.",
      "speaker": 1
    }
  ],
  "teams": [
    {
      "name": "프로덕트",
      "email": null
    }
  ],
  "scope": "workspace",
  "phone_number": null,
  "insight_markdown": "## 요약\n- 제품 출시 일정을 점검한 회의입니다.",
  "link": "https://app.callabo.ai/w/example/record/60234?referer=webhook",
  "transcript": "오늘은 제품 출시 일정을 점검하겠습니다."
}

schema에는 버전 필드가 없습니다. 소비자는 모르는 필드를 무시하고, nullable 필드와 배열이 비어 있는 경우를 허용하도록 구현하세요. 필수 필드의 타입이 맞지 않으면 4xx를 반환해 잘못된 payload를 처리하지 않는 것이 안전합니다.

sample payload와 실제 레코드 테스트하기

Callabo API는 현재 schema로 검증된 Zoom, 전화 통화, 음성 녹음 sample을 제공합니다.

curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=zoom'
curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=phone_call'
curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=voice_recorder'

수신 parser를 만든 뒤 sample echo endpoint로 schema 유효성을 확인할 수 있습니다.

curl -X POST 'https://api.callabo.ai/v1/webhook/sample/echo' \
  -H 'Content-Type: application/json' \
  --data-binary @payload.json

Webhook이 별도로 활성화된 워크스페이스에서 워크스페이스 웹훅 관리 권한이 있으면 전용 테스트 화면으로 정적 sample과 읽을 수 있는 실제 레코드의 payload를 미리 보고 시험 전송할 수 있습니다. 실제 레코드는 processed 상태여야 하며, 미리보기와 시험 전송에도 개인정보 마스킹 정책이 적용됩니다.

재시도와 중복 처리 정책

일반 워크스페이스·팀 Webhook의 전송 규칙은 다음과 같습니다.

첫 요청이 5xx 또는 10초 timeout이면 최대 5번 재시도합니다.
재시도는 1분, 4분, 16분, 64분, 128분 뒤에 수행합니다.
첫 요청을 포함하면 최대 6회이며, 마지막 시도까지 약 3시간 33분이 걸립니다.
3xx, 4xx, DNS·TCP·TLS 같은 transport 연결 오류는 자동 재시도하지 않습니다.
endpoint가 연속 10번 실패하면 circuit이 열려 새 전송을 건너뛸 수 있습니다. 마지막 시도 뒤 1시간이 지나면 복구 확인용 probe 한 번을 허용합니다.
성공 응답을 받으면 해당 endpoint의 연속 실패 수는 0으로 초기화됩니다.

timeout 직전에 수신 서버가 payload를 처리했지만 응답이 늦었다면 같은 payload가 다시 올 수 있습니다. id를 레코드의 business key로 사용하고, body hash로 완전히 같은 payload의 재시도를 제거하세요.

재전사·재처리 후에는 같은 id로 내용이 바뀐 payload가 올 수 있습니다. id만 보고 두 번째 요청을 버리지 말고, 같은 레코드의 최신 snapshot으로 upsert하거나 id + body hash를 별도 delivery key로 저장하는 방식을 권장합니다. 현재 외부 payload에는 내부 처리 세대가 포함되지 않습니다.

운영 체크리스트

사용 플랜, 워크스페이스 활성화와 Webhook 전송 범위를 Callabo 담당자에게 확인했습니다.
공개 https endpoint를 등록했고 redirect가 없습니다.
x-webhook-secret을 secret manager의 값과 비교합니다.
요청을 10초 안에 응답하고 실제 처리는 queue에서 수행합니다.
id + body hash로 재시도 중복과 갱신 payload를 구분합니다.
알 수 없는 필드는 무시하고 nullable·빈 배열을 허용합니다.
전체 transcript, 전화번호, 이메일과 secret을 log에 남기지 않습니다.
저장소 접근 권한과 payload 보존·삭제 주기를 정했습니다.
5xx, timeout, 처리 지연과 재전사 payload를 테스트했습니다.
endpoint 변경이나 폐기 전에 Callabo 설정과 남은 재시도를 확인합니다.

지금 Callabo 시작하기

문의할 때 Webhook secret이나 실제 고객 대화 payload를 보내지 마세요. Callabo 워크스페이스, 레코드 ID, 발생 시각, endpoint domain, HTTP status와 오류 종류만 정리해 채널톡 또는 support@callabo.ai로 문의하세요.

Contents

CALLABO

Callabo Webhook 가이드: 미팅 전사·인사이트 payload 연동하기

jelly

Aug 21, 2026

Contents

Webhook 동작과 전송 범위

Callabo는 레코드의 전사와 후처리가 끝나 processed 상태가 되면 등록된 Webhook을 호출합니다.

워크스페이스 Webhook은 설정된 scope와 레코드의 공개 범위가 일치할 때 전송합니다.
팀 Webhook은 레코드에 연결된 팀의 Webhook 중 설정된 scope와 일치하는 대상에 전송합니다.
하나의 레코드가 여러 팀에 연결돼 있고 각 팀에 endpoint가 있다면 여러 곳으로 전송될 수 있습니다.
재전사나 재처리로 새 처리 세대가 만들어지면 같은 id의 갱신된 payload가 다시 전송될 수 있습니다.
워크스페이스의 Webhook 개인정보 마스킹 정책이 켜져 있으면 제목, 사용자, 전화번호, 대화와 인사이트 일부가 마스킹될 수 있습니다.

수신 endpoint와 인증 요구사항

운영 endpoint는 다음 조건을 만족해야 합니다.

공개 인터넷에서 접근 가능한 https URL을 사용합니다. http도 schema상 허용되지만 운영 환경에서는 사용하지 마세요.
localhost, .localhost, 사설·loopback·link-local·예약 IP로 해석되는 주소는 사용할 수 없습니다.
redirect를 따라가지 않으므로 최종 처리 URL을 직접 등록합니다.
한 번의 요청은 10초 안에 끝나야 합니다.
HTTP 200 이상 300 미만을 반환하면 성공입니다. 응답 body는 일반 전송의 성공 판정에 사용하지 않습니다.
payload가 크거나 후처리가 오래 걸리면 요청을 검증해 queue에 넣고 즉시 200 또는 204를 반환합니다.

Webhook secret을 설정하면 Callabo는 다음 header를 보냅니다.

Content-Type: application/json
x-webhook-secret: <등록한 secret>

다음 Node.js 예시는 secret을 확인하고 무거운 처리를 queue로 넘기는 최소 구조입니다.

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json({ limit: "20mb" }));

app.post("/webhooks/callabo", async (req, res) => {
  const expected = Buffer.from(process.env.CALLABO_WEBHOOK_SECRET ?? "");
  const received = Buffer.from(req.get("x-webhook-secret") ?? "");
  const authenticated =
    expected.length > 0 &&
    expected.length === received.length &&
    crypto.timingSafeEqual(expected, received);

  if (!authenticated) return res.sendStatus(401);
  if (!Number.isInteger(req.body?.id)) return res.sendStatus(400);

  const bodyHash = crypto
    .createHash("sha256")
    .update(JSON.stringify(req.body))
    .digest("hex");

  await enqueueCallaboWebhook({
    recordId: req.body.id,
    bodyHash,
    payload: req.body,
  });
  return res.sendStatus(204);
});

secret이나 전체 payload를 application log에 남기지 마세요. 유출이 의심되면 새 secret으로 endpoint 설정을 교체하고 기존 값을 폐기합니다.

Callabo webhook payload schema

최상위 JSON은 다음 필드를 포함합니다.

필드	타입	nullable	설명
`id`	integer	아니요	Callabo 레코드 ID
`source`	string enum	아니요	녹음·녹화 출처
`owner`	object	예	레코드 소유자
`event`	object	예	연결된 캘린더 일정
`title`	string	아니요	미팅 제목
`duration`	number	예	미팅 길이, 초 단위·최대 소수점 셋째 자리
`start_date`	ISO 8601 datetime	아니요	`rec_date - duration`; duration이 없으면 `rec_date`
`created_at`	ISO 8601 datetime	아니요	Callabo 레코드 생성 시각
`rec_date`	ISO 8601 datetime	아니요	녹음·녹화 종료 시각
`filesize`	integer	아니요	원본 파일 크기, byte
`dialogs`	array	아니요	화자별 발화 목록
`teams`	array	아니요	레코드에 연결된 팀 목록
`scope`	string enum	아니요	`workspace`, `team`, `private`
`phone_number`	string	예	`phone_call` 출처의 상대 전화번호, E.164 형식
`insight_markdown`	string	예	AI 인사이트를 Markdown으로 직렬화한 값
`link`	string	예	Callabo 미팅 상세 링크
`transcript`	string	아니요	`dialogs[].msg`를 줄바꿈으로 합친 전체 대화록

source는 다음 값 중 하나입니다.

zoom
google_meet
teams_meet
phone_call
voice_recorder
screen_recorder
video_recorder
manual_upload

owner와 event

owner는 레코드 소유자가 있을 때 email, name을 포함합니다. 캘린더 일정이 연결된 event는 다음 필드를 가집니다.

필드	타입	설명
`summary`	string	일정 제목
`start`	ISO 8601 datetime	일정 시작 시각
`end`	ISO 8601 datetime	일정 종료 시각
`attendees`	array	참석자의 `email`, `displayName` 목록
`conference_url`	string	온라인 미팅 URL
`recurring`	boolean	반복 일정 여부

일정이 없는 녹음이나 업로드는 event가 null일 수 있습니다. 참석자 이메일이 없는 event attendee는 payload 목록에서 제외됩니다.

dialogs와 teams

teams[]는 name과 선택적인 email을 포함합니다. 전체 대화 문자열이 필요하면 transcript를, 화자와 시각이 필요한 처리는 dialogs를 사용하세요.

webhook payload 예시

아래는 필드를 줄인 Zoom 예시입니다.

{
  "id": 60234,
  "source": "zoom",
  "owner": {
    "email": "ceo@example.com",
    "name": "김대표"
  },
  "event": {
    "summary": "분기 전략 회의",
    "start": "2026-08-18T09:00:00+09:00",
    "end": "2026-08-18T10:00:00+09:00",
    "attendees": [
      {
        "email": "pm@example.com",
        "displayName": "박프로덕트"
      }
    ],
    "conference_url": "https://zoom.us/j/123456789",
    "recurring": false
  },
  "title": "제품 전략 회의",
  "duration": 3600.0,
  "start_date": "2026-08-18T09:00:00+09:00",
  "created_at": "2026-08-18T09:05:00+09:00",
  "rec_date": "2026-08-18T10:00:00+09:00",
  "filesize": 73400320,
  "dialogs": [
    {
      "start_at": 0.0,
      "duration": 15.2,
      "msg": "오늘은 제품 출시 일정을 점검하겠습니다.",
      "speaker": 1
    }
  ],
  "teams": [
    {
      "name": "프로덕트",
      "email": null
    }
  ],
  "scope": "workspace",
  "phone_number": null,
  "insight_markdown": "## 요약\n- 제품 출시 일정을 점검한 회의입니다.",
  "link": "https://app.callabo.ai/w/example/record/60234?referer=webhook",
  "transcript": "오늘은 제품 출시 일정을 점검하겠습니다."
}

sample payload와 실제 레코드 테스트하기

Callabo API는 현재 schema로 검증된 Zoom, 전화 통화, 음성 녹음 sample을 제공합니다.

curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=zoom'
curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=phone_call'
curl 'https://api.callabo.ai/v1/webhook/sample/transcription?source=voice_recorder'

수신 parser를 만든 뒤 sample echo endpoint로 schema 유효성을 확인할 수 있습니다.

curl -X POST 'https://api.callabo.ai/v1/webhook/sample/echo' \
  -H 'Content-Type: application/json' \
  --data-binary @payload.json

재시도와 중복 처리 정책

일반 워크스페이스·팀 Webhook의 전송 규칙은 다음과 같습니다.

첫 요청이 5xx 또는 10초 timeout이면 최대 5번 재시도합니다.
재시도는 1분, 4분, 16분, 64분, 128분 뒤에 수행합니다.
첫 요청을 포함하면 최대 6회이며, 마지막 시도까지 약 3시간 33분이 걸립니다.
3xx, 4xx, DNS·TCP·TLS 같은 transport 연결 오류는 자동 재시도하지 않습니다.
endpoint가 연속 10번 실패하면 circuit이 열려 새 전송을 건너뛸 수 있습니다. 마지막 시도 뒤 1시간이 지나면 복구 확인용 probe 한 번을 허용합니다.
성공 응답을 받으면 해당 endpoint의 연속 실패 수는 0으로 초기화됩니다.

운영 체크리스트

사용 플랜, 워크스페이스 활성화와 Webhook 전송 범위를 Callabo 담당자에게 확인했습니다.
공개 https endpoint를 등록했고 redirect가 없습니다.
x-webhook-secret을 secret manager의 값과 비교합니다.
요청을 10초 안에 응답하고 실제 처리는 queue에서 수행합니다.
id + body hash로 재시도 중복과 갱신 payload를 구분합니다.
알 수 없는 필드는 무시하고 nullable·빈 배열을 허용합니다.
전체 transcript, 전화번호, 이메일과 secret을 log에 남기지 않습니다.
저장소 접근 권한과 payload 보존·삭제 주기를 정했습니다.
5xx, timeout, 처리 지연과 재전사 payload를 테스트했습니다.
endpoint 변경이나 폐기 전에 Callabo 설정과 남은 재시도를 확인합니다.

지금 Callabo 시작하기

문의할 때 Webhook secret이나 실제 고객 대화 payload를 보내지 마세요. Callabo 워크스페이스, 레코드 ID, 발생 시각, endpoint domain, HTTP status와 오류 종류만 정리해 채널톡 또는 support@callabo.ai로 문의하세요.

Contents