웹훅

웹훅은 파트너가 지정한 URL로, RCS for Business 플랫폼이 메시지와 이벤트를 게시합니다. 이 URL은 이벤트에 관한 데이터가 포함된 HTTPS POST 요청을 수신하는 엔드포인트 역할을 합니다. 즉, 데이터가 HTTPS를 통해 애플리케이션으로 안전하게 전송됩니다.

웹훅 URL은 다음과 같이 표시될 수 있습니다. https://[your company name].com/api/rbm-events 웹훅을 구성하면 메시지와 이벤트를 수신할 수 있습니다.

파트너 웹훅 및 에이전트 웹훅

파트너 수준 또는 에이전트 수준에서 웹훅을 구성할 수 있습니다.

  • 파트너 웹훅은 유지관리하는 모든 상담사에게 적용됩니다. 상담사의 동작이 유사하거나 상담사가 한 명인 경우 파트너 웹훅을 사용하세요.
  • 상담사 웹훅은 개별 상담사에 적용됩니다. 동작이 서로 다른 에이전트를 여러 개 운영하는 경우 에이전트마다 다른 웹훅을 설정할 수 있습니다.

파트너 웹훅과 에이전트 웹훅을 모두 구성한 경우 에이전트 웹훅이 특정 에이전트에 우선 적용되고 파트너 웹훅은 자체 웹훅이 없는 에이전트에 적용됩니다.

에이전트 웹훅 구성

파트너 웹훅에서 에이전트에게 전송된 메시지를 수신합니다. 특정 상담사의 메시지가 다른 웹훅에 도착하도록 하려면 상담사 웹훅을 설정하세요.

  1. RCS for Business 개발자 콘솔을 열고 RCS for Business 파트너 Google 계정으로 로그인합니다.
  2. 에이전트를 클릭합니다.
  3. 통합을 클릭합니다.
  4. 웹훅 섹션에서 구성을 클릭합니다.
    1. 웹훅 엔드포인트에 'https://'로 시작하는 웹훅 URL을 입력합니다.
    2. 클라이언트 토큰에 clientToken 값을 지정합니다. 수신한 메시지가 Google에서 전송된 것인지 확인하는 데 필요합니다.

  5. 지정된 clientToken 매개변수가 포함된 POST 요청을 수락하도록 웹훅을 구성하고 secret 매개변수의 일반 텍스트 값이 응답 본문으로 포함된 200 OK 응답을 전송합니다.

    예를 들어 웹훅이 다음 본문 콘텐츠가 포함된 POST 요청을 수신하는 경우

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    그런 다음 웹훅은 clientToken 값을 확인하고 clientToken이 올바르면 1234567890을 응답 본문으로 사용하여 200 OK 응답을 반환해야 합니다.

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  // Use the X-Goog-Webhook-Type header to route requests
  const webhookType = req.header('X-Goog-Webhook-Type');

  if (webhookType === 'verification') {
    const msg = req.body;
    if (msg.clientToken === myClientToken) {
        res.status(200).send(msg.secret);
        return;
    }
  }
  res.send(400);
  // handle other webhook types
});

  6. 개발자 콘솔에서 확인을 클릭합니다. 비즈니스용 RCS에서 웹훅을 인증하면 대화상자가 닫힙니다.

요청 유형 식별

웹훅으로 전송되는 모든 요청의 요청 유형을 식별하려면 X-Goog-Webhook-Type 헤더를 사용하세요.

헤더는 다음 값을 가질 수 있습니다.

  • verification: 초기 엔드포인트 확인 프로세스에 사용됩니다.
  • message_callback: 입력 또는 전송 알림, 사용자로부터 수신된 메시지 등 메시지 관련 이벤트에 사용됩니다.
  • agent_callback: 상담사 실행 상태 변경과 같은 상담사별 관리 이벤트에 사용됩니다.

수신 메일 확인

웹훅은 모든 발신자로부터 메시지를 수신할 수 있으므로 메시지 콘텐츠를 처리하기 전에 Google에서 수신 메시지를 보냈는지 확인해야 합니다.

Google에서 수신한 메시지를 보냈는지 확인하려면 다음 단계를 따르세요.

  1. 메시지의 X-Goog-Signature 헤더를 추출합니다. 메시지 본문 페이로드의 해시되고 base64로 인코딩된 복사본입니다.
  2. 요청의 message.body 요소에서 비즈니스용 RCS 페이로드를 Base-64 디코딩합니다.
  3. 웹훅의 클라이언트 토큰 (웹훅을 설정할 때 지정한 토큰)을 키로 사용하여 base-64로 디코딩된 메시지 페이로드의 바이트에 대한 SHA512 HMAC를 만들고 결과를 base64로 인코딩합니다.
  4. X-Goog-Signature 해시를 생성한 해시와 비교합니다.
    • 해시가 일치하면 Google에서 메시지를 보냈음을 확인한 것입니다.

    • 해시가 일치하지 않으면 알려진 양호한 메시지에서 해싱 프로세스를 확인합니다.

      해싱 프로세스가 올바르게 작동하고 사기로 전송된 것으로 보이는 메시지를 수신한 경우 Google에 문의하세요.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

메시지 처리

웹훅에서 200 OK 이외의 값을 반환하면 전송 실패로 간주됩니다.

개발자는 높은 비율로 메시지를 보내면 높은 비율로 웹훅 알림이 생성된다는 점을 유의해야 하며 예상 비율로 알림을 처리하도록 코드를 설계해야 합니다. 개발자는 웹 컨테이너의 500 응답, 타임아웃, 업스트림 실패 등 실패 응답을 유발할 수 있는 상황을 고려해야 합니다. 고려해야 할 사항은 다음과 같습니다.

  • DDoS 보호가 예상되는 웹훅 알림 비율을 처리하도록 구성되어 있는지 확인합니다.
  • 데이터베이스 연결 풀과 같은 리소스가 소진되어 시간 초과 또는 500 응답이 발생하지 않는지 확인합니다.

개발자는 RBM 이벤트 처리가 비동기적으로 발생하고 웹훅이 200 OK를 반환하지 못하도록 시스템을 설계해야 합니다.

비동기 웹훅 처리

웹훅 내에서 RBM 이벤트를 처리하지 않는 것이 중요합니다. 처리 중 오류나 지연이 발생하면 웹훅 반환 코드에 영향을 미칠 수 있습니다.

동기 웹훅 처리

전송 실패 시 동작

웹훅이 200 OK 상태 이외의 값을 반환하면 비즈니스용 RCS 플랫폼에서 지연 및 재시도 메커니즘을 사용하여 데이터를 다시 전송합니다. 즉, 시스템은 각 전송 시도 간의 지연 시간을 점진적으로 늘려 결국 각 대기 중인 메시지에 대해 10분마다 한 번의 재시도라는 최대 빈도에 도달합니다. 재시도 주기는 7일 동안 계속되며, 이후에는 메시지가 영구적으로 삭제됩니다.

에이전트 수준 웹훅의 영향

비즈니스용 RCS는 파트너의 메시지를 하나의 대기열에 대기시킵니다. 단일 파트너 계정의 모든 상담사는 단일 대기열을 공유합니다. 따라서 하나의 웹훅에 오류가 발생하면 전체 대기열이 차단되어 모든 상담사의 사용자 이벤트가 파트너에게 도달하지 못할 수 있습니다.

확인되지 않은 메시지가 여러 개 있으면 재시도 이벤트가 급증할 수 있습니다. 예를 들어 에이전트가 1,600개의 전송 확인을 승인하지 않고 재시도 빈도가 10분 한도에 도달하면 하루에 약 230,000개의 잠재적 오류가 발생할 수 있습니다.

1,600개 메시지 × 시간당 6회 재시도 × 일일 24시간 = 일일 약 230,000개 오류

이러한 재시도 횟수가 많으면 공유 Pub/Sub 대기열이 차단되어 파트너의 모든 캠페인에서 사용자 이벤트 수신이 크게 지연될 수 있습니다.

권장사항

프로덕션 트래픽의 안정성을 확보하고 대기열 차단기를 방지하려면 다음 권장사항을 따르세요.

  • 즉시 200 OK 반환: 웹훅은 메시지를 수신하고, 로컬 대기열에 저장하고, 5초 이내에 200 OK 응답을 반환해야 합니다.
  • 처리 분리: 별도의 백그라운드 작업자를 사용하여 로컬 대기열에서 메시지 로직을 처리합니다.
  • 테스트 에이전트 모니터링: 개발 에이전트가 실패하면 공유 파트너 대기열을 차단할 수도 있으므로 개발 에이전트를 프로덕션 에이전트처럼 취급합니다.
  • 테스트용 전용 계정: 프로덕션 에이전트에는 하나의 개발자 계정을 사용하고 테스트 에이전트에는 전용 개발자 계정을 사용하는 것이 좋습니다.
  • Google 트래픽 확인: Google은 동적 애니캐스트 IP를 사용하므로 고정 IP 허용 목록 대신 역방향 DNS 또는 X-Goog-Signature 헤더를 사용하세요. 수동 확인 및 Google IP 범위 식별에 관한 자세한 내용은 Google 요청 확인 문서와 특히 사용자 트리거 가져오기 도구 및 Google 사용자 트리거 가져오기 도구의 JSON 파일을 참고하세요.

다음 단계

웹훅을 구성하면 에이전트가 테스트 기기에서 메시지를 수신할 수 있습니다. 메시지를 보내 설정을 확인합니다.

다음
Dialogflow