리포트·웹훅

발송 결과는 접수 결과일 뿐이고, 최종 수신 결과는 리포트로 받습니다. 리포트 수신 방식(POLLING 또는 WEBHOOK)은 콘솔에서 API Key별로 정합니다.

방식	언제 쓰나	SDK
Polling	서버가 외부에서 호출을 받을 수 없을 때	`reports.consume`
Webhook	비즈고가 내 서버로 바로 보내 주길 원할 때	`WebhookReceiver`
개별 조회	특정 메시지 하나의 결과를 확인할 때 (30일 이내)	`reports.inquiry`

Polling

처리에 성공한 배치만 수신 확인(ack)합니다. 처리 함수가 예외(Go는 오류 반환)를 내면 같은 배치를 다시 받습니다. 같은 리포트가 다시 올 수 있으니 저장은 msgKey 기준 upsert로 하세요.

Java

int handled = client.reports().consume(reports -> {
    for (Report r : reports) {
        db.upsert(r.getMsgKey(), r.getReportCode());
    }
});

Webhook

비즈고가 보낸 요청의 서명을 검증하고, 5초 안에 {"msgKey": ...}로 응답합니다. 서명이 틀리면 401로 응답하세요. 웹훅 secret은 비즈고에 요청해 별도로 받고, 환경변수 BIZGO_WEBHOOK_SECRET처럼 코드 밖에 둡니다.

Java

WebhookReceiver receiver = new WebhookReceiver(System.getenv("BIZGO_WEBHOOK_SECRET"));

// 사용하는 웹 프레임워크의 핸들러 안에서
try {
    ReportWebhookPayload report = receiver.report(headers, rawBody);
    enqueue(report);                                   // 무거운 처리는 비동기로
    return ok(Webhooks.ackJson(report.getMsgKey()));   // {"msgKey":"..."}
} catch (WebhookVerificationException e) {
    return status(401);
}

보안. SDK는 서명과 timestamp 허용 오차(기본 300초)를 검증하고, 본문은 최대 1MB·JSON 깊이 64단계까지만 받습니다. 운영 환경에서는 HTTPS, 비즈고 웹훅 발신 IP 허용 목록, msgKey 기준 중복 제거를 함께 적용하고, 중요한 판단은 리포트·상태 조회 API로 결과를 다시 확인하세요.

카카오 상담톡 웹훅 7종(counsel_message, counsel_result, counsel_reference, counsel_expired_session, counsel_seen_info, counsel_personal_info, counsel_cert_result)도 SDK로 파싱할 수 있습니다. 리포트 웹훅과 다른 점은 다음과 같습니다.

서명이 없습니다. 서명은 리포트·MO 웹훅에만 적용되므로, 상담톡만 받는다면 웹훅 secret이 필요 없습니다.
응답은 {"msgKey"}가 아니라 {"code": "A000", "result": "Success"}입니다.
본문에 상담 내용과 개인정보가 들어 있으니 로그·APM·에러 리포트에 남기지 마세요.

언어별 함수 이름은 각 저장소 README의 상담톡 웹훅 절을 참고하세요.

개별 조회

msgKey 하나의 리포트를 직접 조회합니다. 발송 후 30일 이내만 조회할 수 있습니다.

Java

client.reports().inquiry(msgKey);