웹훅

웹훅은 비즈니스 로직을 호스팅하는 서비스입니다. 세션 중에 웹훅을 사용하면 Dialogflow의 자연어 처리에서 추출한 데이터를 사용하여 동적 응답을 생성하거나, 수집된 데이터를 검증하거나, 백엔드에서 작업을 트리거할 수 있습니다.

CX 웹훅은 요청 및 응답 필드가 CX 기능을 지원하도록 변경되었다는 점을 제외하면 ES 웹훅과 유사합니다.

웹훅 서비스 요구사항

웹훅 서비스에서 다음 요구사항을 충족해야 합니다.

• HTTPS 요청을 처리해야 합니다. HTTP는 지원되지 않습니다. Compute 또는 서버리스 컴퓨팅 솔루션을 사용하여 Google Cloud Platform에서 웹훅 서비스를 호스팅하는 경우 HTTPS와 함께 제공되는 제품 문서를 참조하세요. 다른 호스팅 옵션은 도메인의 SSL 인증서 받기를 참조하세요.
• 요청 URL은 공개적으로 액세스할 수 있어야 합니다.
• JSON WebhookRequest 본문으로 POST 요청을 처리해야 합니다.
• JSON WebhookResponse 본문으로 WebhookRequest 요청에 응답해야 합니다.
• 에이전트가 서비스 디렉터리 비공개 네트워크 액세스와 통합되지 않으면 웹훅 호출이 서비스 경계 외부로 간주되어 VPC 서비스 제어를 사용 설정할 때 차단됩니다. 제한된 엔드포인트는 서비스 디렉터리에서 지원됩니다. 자세한 내용은 서비스 디렉터리를 참조하세요.

인증

본인 또는 Dialogflow 에이전트만 요청을 실행할 수 있도록 웹훅 서비스를 보호하는 것이 중요합니다. 웹훅 서비스 보호는 웹훅 리소스를 만들 때 구성합니다. Dialogflow CX는 인증을 위해 다음과 같은 메커니즘을 지원합니다.

• 인증 헤더를 사용한 인증
• Cloud Functions 사용
• 서비스 ID 토큰
• 상호 TLS 인증

참고: Dialogflow는 웹훅 요청을 보내는 머신의 IP 범위에 대해 어떠한 보장도 할 수 없습니다. IP 범위를 통해 액세스를 제한하는 대신 위에 나열된 인증 방법 중 하나를 사용해야 합니다.

HTTPS 인증서 확인

Dialogflow는 기본적으로 Google의 기본 트러스트 저장소를 사용하여 HTTPS 인증서를 확인합니다. 자체 서명된 인증서 또는 커스텀 루트 인증서와 같이 Google의 기본 트러스트 저장소에서 인식하지 못하는 인증서를 HTTPS 서버에 사용하려면 커스텀 CA 인증서를 참조하세요.

웹훅 요청

웹훅이 포함된 fulfillment가 호출되면 Dialogflow는 웹훅 서비스에 HTTPS POST 웹훅 요청을 보냅니다. 이 요청의 본문은 일치된 인텐트에 대한 정보가 있는 JSON 객체입니다.

자세한 내용은 WebhookRequest(V3) 또는 WebhookRequest(V3Beta1) 참조 문서를 확인하세요.

웹훅 응답

웹훅 서비스가 웹훅 요청을 받으면 웹훅 응답을 보내야 합니다. 응답에 대해 다음 제한사항이 적용됩니다.

• 응답은 웹훅 리소스를 만들 때 구성한 제한 시간 내에 발생해야 하며 그렇지 않으면 요청이 타임아웃됩니다.
• 응답 크기는 64KiB 이하여야 합니다.

자세한 내용은 WebhookResponse(V3) 또는 WebhookResponse(V3Beta1) 참조 문서를 확인하세요.

웹훅 리소스 만들기

웹훅 서비스가 실행 중이면 에이전트에 연결 및 인증 정보가 있는 웹훅 리소스를 만들어야 합니다. 웹훅 리소스를 만들려면 다음 안내를 따르세요.

Console

1. Dialogflow CX 콘솔을 엽니다.
2. GCP 프로젝트를 선택합니다.
3. 에이전트를 선택합니다.
4. 관리 탭을 선택합니다.
5. 웹훅을 클릭합니다.
6. 만들기를 클릭합니다.
7. 웹훅 데이터를 입력합니다.
8. 저장을 클릭합니다.

API

Webhook 유형은 create 메서드를 참조하세요. Webhook API 참조로 이동

웹훅 참조의 프로토콜 및 버전 선택:

프로토콜	V3	V3beta1
REST	웹훅 리소스	웹훅 리소스
RPC	웹훅 인터페이스	웹훅 인터페이스
C#	해당 사항 없음	해당 사항 없음
Go	해당 사항 없음	해당 사항 없음
자바	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	해당 사항 없음	해당 사항 없음
Python	WebhooksClient	WebhooksClient
Ruby	해당 사항 없음	해당 사항 없음

닫기

웹훅 오류

웹훅 서비스가 웹훅 요청을 처리하는 동안 오류가 발생하면 웹훅 코드가 다음 HTTP 상태 코드 중 하나를 반환해야 합니다.

• 400 잘못된 요청
• 401 승인되지 않음
• 403 금지됨
• 404 찾을 수 없음
• 500 서버 오류
• 503 서비스를 사용할 수 없음

다음과 같은 오류 상황에서 Dialogflow는 웹훅 오류 또는 제한 시간 기본 제공 이벤트를 호출하고 평소처럼 처리를 진행합니다.

• 응답 제한 시간을 초과했습니다.
• 오류 상태 코드가 수신되었습니다.
• 응답이 잘못되었습니다.
• 웹훅 서비스를 사용할 수 없습니다.

또한 인텐트 인식 API 호출에 의해 웹훅 서비스 호출이 트리거된 경우 인텐트 인식 응답의 queryResult.webhookStatuses 필드에 웹훅 상태 정보가 포함됩니다.

Cloud Functions 사용

Dialogflow는 Cloud Functions와 통합되므로 안전한 서버리스 웹훅을 손쉽게 만들 수 있습니다. 에이전트와 동일한 프로젝트에 있는 함수를 만들면 에이전트가 특별한 구성 없이 웹훅을 안전하게 호출할 수 있습니다.

그러나 다음 두 상황에서는 이 통합을 수동으로 설정해야 합니다.

1. 에이전트 프로젝트에 다음 주소를 사용하는 Dialogflow Service Agent 서비스 계정이 있어야 합니다.

   [e-mail]

   이 특수 서비스 계정과 연결된 키는 일반적으로 프로젝트의 첫 번째 에이전트를 만들 때 자동으로 생성됩니다. 에이전트를 2020년 11월 1일 이전에 만든 경우 이 특별 서비스 계정 생성을 트리거할 수 있습니다.
   1. 프로젝트의 새 에이전트를 만듭니다.
   2. 다음 명령어를 실행합니다.

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. 웹훅 함수가 에이전트가 아닌 다른 프로젝트에 있는 경우Cloud Functions 호출자 IAM 역할을 함수의 프로젝트의 Dialogflow 서비스 에이전트 서비스 계정에 제공해야 합니다.

비공개 네트워크 액세스에 서비스 디렉터리 사용

Dialogflow는 서비스 디렉터리 비공개 네트워크 액세스와 통합되므로 VPC 네트워크 내의 웹훅 대상에 연결할 수 있습니다. 이렇게 하면 트래픽이 Google Cloud 네트워크 내에서 유지되며 IAM 및 VPC 서비스 제어가 적용됩니다.

참고: Cloud Functions는 현재 VPC 서비스 제어 경계에서 지원되지 않습니다.

비공개 네트워크를 타겟팅하는 웹훅을 설정하려면 다음 안내를 따르세요.

1. 서비스 디렉터리 비공개 네트워크 구성을 따라 VPC 네트워크와 서비스 디렉터리 엔드포인트를 구성합니다.
2. 에이전트 프로젝트에 다음 주소를 사용하는 Dialogflow Service Agent 서비스 계정이 있어야 합니다.

   [e-mail]

   Dialogflow Service Agent 서비스 계정에 다음 IAM 역할을 부여합니다.
   • 서비스 디렉터리 프로젝트의 servicedirectory.viewer
   • 네트워크 프로젝트의 servicedirectory.pscAuthorizedService

3. 웹훅을 만들 때 URL 및 선택적 인증 정보와 함께 서비스 디렉터리 서비스를 제공합니다.

   Console

   

   API

   Webhook 유형의 serviceDirectory 필드를 참조하세요. Webhook API 참조로 이동

   웹훅 참조의 프로토콜 및 버전 선택:

   프로토콜	V3	V3beta1
   REST	웹훅 리소스	웹훅 리소스
   RPC	웹훅 인터페이스	웹훅 인터페이스
   C#	해당 사항 없음	해당 사항 없음
   Go	해당 사항 없음	해당 사항 없음
   자바	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	해당 사항 없음	해당 사항 없음
   Python	WebhooksClient	WebhooksClient
   Ruby	해당 사항 없음	해당 사항 없음

   닫기

서비스 ID 토큰

Dialogflow가 웹훅을 호출할 때 요청과 함께 Google ID 토큰을 제공합니다. 모든 웹훅은 Google 클라이언트 라이브러리 또는 github.com/googleapis/google-auth-library-nodejs와 같은 오픈소스 라이브러리를 사용하여 토큰을 선택적으로 검증할 수 있습니다. 예를 들어 다음과 같이 ID 토큰의 email을 확인할 수 있습니다.

[e-mail]