웹훅

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

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

파트너 웹훅 및 상담사 웹훅

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

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

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

상담사 웹훅 구성

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

Business Communications Developer Console을 열고 RBM 파트너 Google 계정으로 로그인합니다.
상담사를 클릭합니다.
통합을 클릭합니다.
Webhook에서 구성을 클릭합니다.
웹훅 엔드포인트 URL에 'https://'로 시작하는 웹훅 URL을 입력합니다.
clientToken 값을 기록합니다. 수신한 메일이 Google에서 보낸 메시지인지 확인하는 데 필요합니다.
지정된 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) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});
```
Developer Console에서 확인을 클릭합니다. RBM에서 웹훅을 확인하면 대화상자가 닫힙니다.

수신 메일 확인

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

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

메시지의 X-Goog-Signature 헤더를 추출합니다. 메시지 본문 페이로드의 해싱된 base64 인코딩 사본입니다.
요청의 message.body 요소에서 RBM 페이로드를 Base64로 디코딩합니다.
webhook의 클라이언트 토큰 (webhook 설정 시 지정)을 키로 사용하여 base64 디코딩된 메시지 페이로드의 바이트로 SHA512 HMAC을 만들고 결과를 base64로 인코딩합니다.
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
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

메시지 처리

webhook에서 200 OK 이외의 항목을 반환하면 전송 실패로 간주됩니다.

개발자는 메시지를 빠른 속도로 전송하면 webhook 알림이 빠른 속도로 생성된다는 점에 유의해야 하며 예상 속도로 알림을 사용할 수 있도록 코드를 설계해야 합니다. 개발자는 웹 컨테이너의 500 응답, 시간 초과 또는 업스트림 실패 등 실패 응답을 일으킬 수 있는 상황을 고려해야 합니다. 고려해야 할 사항은 다음과 같습니다.

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

전송 실패 시 동작

RBM은 웹훅 호출에서 200 OK이 아닌 응답을 수신하면 백오프 및 재시도 메커니즘을 사용합니다. RBM은 재시도 사이의 대기 시간을 최대 600초까지 늘립니다. 재시도는 7일 동안 계속되며 그 후에는 메시지가 삭제됩니다.

상담사 수준 웹훅의 의미

RBM은 파트너의 메시지를 하나의 큐에 큐에 추가합니다. 파트너가 상담사 수준 webhook을 사용하는 경우 한 webhook의 실패가 다른 webhook에 대한 전송에 영향을 미친다는 점에 유의해야 합니다. 다른 상담사 소유의 웹훅은 메시지 실패의 백오프 기간 동안 호출됩니다. 하지만 실패한 메시지가 재시도를 위해 대기열에 추가되면 전반적인 전송 비율이 떨어지고 다른 상담사가 영향을 받습니다.

개발자는 이 모델을 이해하고 그에 따라 코딩해야 합니다. 최대한 메시지를 수락하고 처리를 위해 메시지를 큐에 추가하여 실패를 반환할 가능성을 최소화해야 합니다.

다음 단계

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