Callback(메시지 수신)

봇이 받은 메시지와 이벤트 정보를 callback으로 봇 서버가 수신할 수 있다.
Developer Console의 봇에서 지정한 Callback URL(봇 서버)로 이벤트 객체가 포함된 HTTPS POST 요청이 전송된다.

주의

• Callback Url은 보안상의 이유로 자체 서명된 인증서를 허용하지 않는다.
• 허용된 인증 기관 목록은 CA 목록을 참고한다.

Callback 이벤트 수신 시 처리 흐름 {#callback-flow}

Callback 이벤트 요청에서 응답까지의 흐름은 다음과 같다.

참고

• HTTPS POST 요청 처리 때문에 후속 이벤트 처리가 지연되지 않도록 이벤트 처리를 비동기(async)로 구현해야 한다.

Callback 요청 정보 {#request-from-message-server}

메시지방에 참여하거나 메시지를 보내는 것과 같은 이벤트가 발생하면 Callback URL(봇 서버)에 HTTPS POST 요청이 전송된다.

요청 헤더 {#request-header}

주의

• 요청 헤더의 필드 이름은 대소문자를 구분하지 않고 처리해야 한다. 표기가 예고 없이 변경될 수 있다.
• 자세한 내용은 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing의 3.2 Header Fields를 참고한다.

요청 본문 {#request-body}

사용자의 userId, 메시지방의 channelId 또는 메시지 내용 등의 정보를 포함하며, JSON 형식으로 되어있다.

예시) Message Event

{   "type": "message",   "source": {     "userId": "c72af563-0f21-4736-11e4-045237113344",     "channelId": "12345a12-b12c-12d3-e123fghijkl",     "domainId": 40029600   },   "issuedTime": "2022-01-04T05:16:05.716Z",   "content": {     "type": "text",     "text": "hello"   }}

내용은 Callback 이벤트 유형에 따라 다르다. 자세한 내용은 각 이벤트 유형 페이지를 참고한다.

서명 확인 {#verify-signature}

주의

• 봇 서버가 수신한 HTTPS POST 요청은 항상 서명을 확인한 다음 이벤트 객체를 처리해야 한다.

수신한 요청이 NAVER WORKS로부터 전달된 것임을 확인하기 위해 요청 헤더의 X-WORKS-Signature에 포함된 서명을 검증한다.

1. Developers Console의 Bot에서 봇 상세 화면을 열고 Bot Secret을 확인한다.
2. Bot Secret을 개인 키로 사용해 수신한 요청 본문을 HMAC-SHA256 알고리즘으로 인코딩한다.
3. 인코딩된 결과를 Base64 인코딩한다.
4. X-WORKS-Signature의 값과 비교하여 일치하는지 확인한다.

주의

• Bot Secret이 외부로 유출되지 않도록 주의한다.

Java로 서명 검증을 구현하는 예는 다음과 같다.

String botSecret = ...;String httpRequestBody = ...; // Request body stringSecretKeySpec key = new SecretKeySpec(botSecret.getBytes(), "HmacSHA256");Mac mac = Mac.getInstance("HmacSHA256");mac.init(key);byte[] source = httpRequestBody.getBytes("UTF-8");String signature = Base64.encodeBase64String(mac.doFinal(source));// Compare X-WORKS-Signature request header and the signature// signature == headers_signature

Python의 구현 예는 다음과 같다.

import base64import hashlibimport hmacbot_secret = '...' # Bot Secret stringbody = '...' # Request body stringhash = hmac.new(bot_secret.encode('utf-8'),     body.encode('utf-8'), hashlib.sha256).digest()signature = base64.b64encode(hash)# Compare X-WORKS-Signature request header and the signature#signure == headers_signature

Callback 이벤트 유형 {#callback-event-type}

Callback 이벤트의 종류는 다음과 같다. 봇과의 1:1 메시지방과 1:N 메시지방은 받을 수 있는 이벤트가 다르다.

자세한 내용은 각 이벤트 유형 페이지를 참고한다.

사용자 정보 얻기 {#get-user-info}

이벤트 객체에는 메시지를 전송한 사용자의 userId가 포함되어 있다. 이 ID를 사용하면 사용자의 이름, 이메일 주소 등의 정보를 얻을 수 있다.

사용자 정보 얻기는 Directory API 개요를 참고한다. 액세스 토큰 발급 시 지정한 Scope에 따라 취득할 수 있는 사용자 정보가 다르다.

자세한 내용은 각 API 페이지를 참고한다.

응답(메시지 보내기) {#reply}

봇의 응답은 봇 API의 메시지 전송을 사용한다. 자세한 내용은 봇 API 개요를 참고한다.

NAVER WORKS에 대한 응답 {#response}

Callback을 받은 봇 서버에서 NAVER WORKS로 HTTP 코드 200을 반환해야 한다.