웹훅 알림

사용자가 요청한 모든 이벤트와 게임을 수동으로 모니터링하는 대신, 웹훅을 설정하여 타사 메시징 도구 또는 HTTP 요청을 수신할 수 있는 사용자 정의 엔드포인트에서 실시간 알림을 받을 수 있습니다. 이는 알림 관리 워크플로를 자동화하여 알림을 처리하는 수동 작업을 줄이는 데 도움을 줍니다.

웹훅 워크플로

웹훅은 Roblox와 타사 메시징 도구와 같은 두 개의 서로 다른 응용 프로그램 또는 서비스 간에 실시간 알림이나 데이터를 전송합니다. 데이터를 수신하기 위해 서버에 요청을 보내는 클라이언트 응용 프로그램을 설정해야 하는 전통적인 API와 달리, 웹훅은 이벤트가 발생하면 즉시 클라이언트 엔드포인트로 데이터를 전송합니다. 이는 Roblox와 팀과 협업하는 데 사용하는 타사 응용 프로그램 간의 워크플로를 자동화하는 데 유용하며, 이는 실시간 데이터 공유 및 처리를 가능하게 합니다.

웹훅을 설정하면, 특정 이벤트가 발생할 때마다 Roblox는 제공한 웹훅 URL로 요청을 보냅니다. 웹훅 URL은 요청을 수신 애플리케이션이나 사용자 정의 엔드포인트로 리디렉션하며, 해당 엔드포인트는 웹훅 페이로드에 포함된 데이터에 따라 조치를 취할 수 있습니다. 여기에는 RTBF 준수를 위한 데이터 삭제, 사용자에게 확인 메시지 전송 또는 다른 이벤트 발동 등이 포함될 수 있습니다.

지원되는 트리거

Roblox는 현재 다음 이벤트 트리거를 지원합니다.

구독

• 구독 재구독됨 - 사용자가 구독을 재구독할 때 구독 및 구독자 정보를 포함하는 메시지가 전송됩니다.
• 구독 갱신됨 - 사용자가 구독을 갱신할 때 구독 및 구독자 정보를 포함하는 메시지가 전송됩니다.
• 구독 환불됨 - 사용자가 구독에 대한 환불을 받을 때 구독 및 구독자 정보를 포함하는 메시지가 전송됩니다.
• 구독 구매됨 - 사용자가 구독을 구매할 때 구독 및 구독자 정보를 포함하는 메시지가 전송됩니다.
• 구독 취소됨 - 사용자가 구독을 취소할 때 구독 및 구독자 정보를 포함하고, 취소 사유도 포함된 메시지가 전송됩니다.

구독 이벤트 및 필드에 대한 자세한 내용은 구독 참조를 확인하십시오.

준수

• 삭제 권리 / 삭제 요청 - 사용자가 적용되는 글로벌 데이터 보호 및 개인 정보 보호 규정에 따라 개인 정보를 영구적으로 삭제할 권리를 행사할 때 발생합니다. 자세한 내용은 RTBF 및 제작자를 참조하십시오.

상거래

• 상거래 제품 주문 환불 - 사용자가 상거래 제품 주문에 대한 환불을 받을 때 발생하거나 주문이 취소된 경우입니다.
• 상거래 제품 주문 결제됨 - 사용자가 상거래 제품 주문을 결제했을 때 발생합니다. 중복 웹훅 이벤트가 발생할 수 있으므로 고유한 상거래 주문 ID를 사용하여 이벤트를 중복 제거해야 합니다.

제작자 대시보드에서 웹훅 구성

웹훅을 통해 알림을 수신하려면 알림을 트리거할 특정 이벤트에 구독하는 웹훅을 구성해야 합니다. 그룹 소유 게임의 경우 그룹 소유자만 웹훅 알림을 구성하고 받을 수 있습니다.

웹훅을 설정하려면:

1. Creator Hub에서 본인의 경험을 선택하십시오.

2. 구성에서 웹훅을 선택하고 웹훅 추가를 클릭하십시오.

   웹훅 URL은 제공업체에서 가져옵니다. 예를 들어, Slack URL은 아마 다음과 같을 것입니다:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. 웹훅 URL과 이름을 입력하십시오.

4. (선택 사항) 비밀을 포함하십시오. 이는 수신하는 알림이 Roblox에서 오는 것인지 확인하는 데 도움이 됩니다. 더 많은 정보는 웹훅 보안 확인을 참조하십시오.

5. 알림을 받고자 하는 이벤트의 지원되는 트리거 목록에서 하나 이상의 옵션을 선택하십시오.

6. (선택 사항) 테스트 응답 버튼을 사용하여 서비스가 샘플 요청을 수신할 수 있는지 확인하십시오.

7. 변경 사항 저장을 클릭하십시오.

웹훅 URL 설정

웹훅 URL로 사용자 정의 HTTP 서비스 엔드포인트를 설정할 수 있지만, 다음 요구 사항을 충족해야 합니다:

• 요청 처리를 위해 공개적으로 액세스 가능해야 합니다.
• POST 요청을 처리할 수 있어야 합니다.
• 요청에 대해 5초 이내에 2XX 응답을 반환할 수 있어야 합니다.
• HTTPS 요청을 처리할 수 있어야 합니다.

귀하의 엔드포인트가 POST 요청을 수신할 때, 다음을 수행할 수 있어야 합니다:

• POST 메시지 본문에서 알림에 대한 세부 정보를 추출합니다.
• 알림의 일반 세부 정보 및 알림의 이벤트 유형과 관련된 특정 세부 정보를 읽습니다.

POST 요청을 처리하기 위한 스키마에 대한 자세한 정보는 페이로드 스키마를 참조하십시오.

배달 실패 재시도 정책

웹훅 알림이 지정된 URL에 도달하지 못할 경우, Roblox는 고정된 윈도우 크기를 사용하여 구성된 URL로 메시지를 5번 재전송합니다. 5번의 시도가 실패하면, Roblox는 더 이상 알림을 전송하려고 시도하지 않으며 URL이 더 이상 유효하지 않다고 가정합니다. 이 경우, 도달 가능하고 알림을 수신할 수 있는 새로운 URL로 웹훅 구성을 업데이트해야 합니다. 웹훅 URL이 성공적으로 알림을 수신할 수 있는지 확인하고 문제를 해결하려면 웹훅 테스트를 참조하십시오.

타사 요구 사항

타사 도구는 웹훅 URL 설정 시 따라야 할 자체 요구 사항이 있는 경우가 많습니다. 이러한 요구 사항은 타겟 도구의 지원 또는 문서 사이트에서 "웹훅" 키워드를 검색하여 찾을 수 있습니다. 지원되는 타사 도구에 대한 내용은 다음과 같습니다:

• Discord 도움말 센터
• Slack API 참조

웹훅 테스트

Creator Dashboard에서 구성한 웹훅이 성공적으로 알림을 수신할 수 있는지 테스트할 수 있습니다:

1. 웹훅 구성 페이지로 이동합니다.
2. 구성된 웹훅 목록에서 테스트할 웹훅을 선택합니다.
3. 대상 웹훅 옆의 연필 아이콘을 클릭합니다.
4. 테스트 응답 버튼을 클릭합니다.

시스템은 이후, User ID를 포함하여 알림을 트리거한 사용자의 정보를 포함하는 SampleNotification 이벤트를 전송합니다. 결과는 다음과 같습니다:

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

타사 서비스와 웹훅을 통합하는 경우, 타사 URL를 사용하여 성공적으로 알림을 받을 수 있는지 테스트할 수 있습니다. 웹훅 구성 시 비밀을 제공한 경우, roblox-signature가 생성되어 roblox-signature 로직을 테스트하는 데 사용할 수 있습니다.

웹훅 보안 확인

서버를 구성하여 페이로드를 수신하도록 설정한 후, 엔드포인트로 전송되는 모든 페이로드를 수신 대기하기 시작합니다. 웹훅 구성 시 비밀을 설정한 경우, Roblox는 각 웹훅 알림에 roblox-signature를 전송하여 요청이 실제로 Roblox에서 온 것인지 확인합니다. 이 서명은 사용자 정의 엔드포인트의 페이로드 헤더에 포함되며, 타사 서버의 바닥글에 포함됩니다.

t=<timestamp>,v1=<signature>

웹훅에 대해 비밀을 설정하지 않은 경우, 서명에는 알림이 전송된 시간의 타임스탬프만 포함됩니다:

t=<timestamp>

서명을 확인하려면:

1. 타임스탬프와 서명 값을 추출합니다. 비밀이 있는 웹훅의 모든 서명은 다음 두 값을 포함한 CSV 문자열 형식을 공유합니다:

   • t: 알림이 전송된 타임스탬프.
   • v1: 제작자 대시보드 구성에서 제공된 비밀을 사용하여 생성된 서명 값.

2. roblox-signature의 기본 문자열을 재구성합니다:

   1. 타임스탬프를 문자열로 변환합니다.
   2. 마침표 문자 .를 추가합니다.
   3. 요청 본문의 JSON 문자열을 추가합니다.

3. 설정한 비밀을 키로 사용하여 SHA256 해시 함수를 이용한 해시 기반 메시지 인증 코드(HMAC)를 계산합니다. 이 단계에서 생성한 기본 문자열을 메시지로 사용하고, 결과를 Base64 형식으로 변환하여 예상 서명을 얻습니다.

4. 추출한 서명 값이 예상 서명과 일치하는지 비교합니다. 서명을 올바르게 생성했다면 두 값이 같아야 합니다.

5. (선택 사항) 재전송 공격을 방지하기 위해, 재전송 공격은 공격자가 데이터를 가로챈 후 재전송하여 무단 액세스 또는 악의적인 작업을 수행하는 사이버 공격의 일종입니다. 추출한 타임스탬프 값을 현재 타임스탬프와 비교하여 합리적인 시간 제한 내에 있는지 확인하는 것이 좋습니다. 예를 들어, 보통 10분 정도의 시간 제한이 적당합니다.

페이로드 스키마

웹훅의 목표 이벤트가 트리거될 때, 요청이 웹훅 URL로 전송되며 페이로드에 이벤트에 대한 정보가 포함됩니다. 모든 요청의 페이로드는 동일한 스키마에 따라 고정 및 가변 필드를 포함합니다. 이는 페이로드에 전송되는 데이터가 구조적이고 일관되게 유지되도록 하여 수신 애플리케이션이 데이터를 처리하고 사용하는 것을 더 쉽게 만듭니다.

고정 페이로드 스키마 필드는 모든 웹훅 요청 간의 일관성을 유지하는 데 도움을 주며, 다음 필드가 제공됩니다:

1. NotificationId (string): 전송된 각 알림에 대한 고유 식별자입니다. 동일한 NotificationId를 두 번 수신하면 중복으로 간주됩니다.
2. EventType (string): 알림이 트리거된 이벤트의 유형을 나타냅니다.
3. EventTime (string): 이벤트가 트리거된 시간의 타임스탬프입니다.

가변 페이로드 스키마 필드는 다양한 유형의 이벤트를 수용하기 위해 웹훅의 유연성을 제공합니다. 포함된 필드는 다음과 같습니다:

1. EventPayload (object): 웹훅을 트리거한 EventType와 관련된 특정 정보를 포함합니다. EventPayload 스키마의 구조는 이벤트 유형에 따라 달라집니다.

다음 예시는 삭제 권리 요청 이벤트의 페이로드 스키마를 보여줍니다:

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

알림 처리

사용자의 **개인 식별 정보(PII)**를 저장하는 경우, 예를 들어 사용자 ID와 같은 정보를 저장하는 경우 법적 의무에 비추어 요청을 평가해야 합니다. 자세한 내용은 RTBF 및 제작자에서 확인할 수 있습니다. 웹훅 알림을 처리하고 데이터 삭제를 자동화하는 봇을 생성할 수 있으며, 이는 PII를 데이터 저장소에 저장하는 경우에 유효합니다. 삭제 권리 요청 처리 자동화에서 PII 데이터 삭제를 위한 Open Cloud API 데이터 저장소를 사용하는 Discord 내에서 봇을 만드는 예제를 확인하십시오. 이 예제는 구독 이벤트와 같은 다른 알림을 처리하는 데에도 적용할 수 있습니다.

타사 도구 대신 웹훅 서버로 사용자 정의 엔드포인트를 사용하는 경우, 웹훅 페이로드에서 삭제할 데이터를 추출하여 자신의 자동화 솔루션을 구축할 수 있습니다. 아래 코드 샘플은 타임스탬프를 확인하고 요청이 Roblox에서 오는지를 검증하는 재전송 공격 예방 기능이 있는 서버의 예입니다:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // 환경 변수를 설정할 수 있습니다

let app = express();
app.use(express.json());

app.all('/*', function (req, res) {
   console.log('새 요청 수신됨');

   // 헤더에서 타임스탬프와 서명 추출
   const signatureHeader = req.headers['roblox-signature'].split(',');
   const timestamp = signatureHeader.find(e => e.startsWith('t=')).substring(2);
   const signature = signatureHeader.find(e => e.startsWith('v1=')).substring(3);

   // 재전송 공격을 방지하기 위해 요청이 300초 윈도우 내에 있는지 확인
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('만료된 요청');
   }

   // 서명 검증
   const message = `${timestamp}.${JSON.stringify(req.body)}`;
   const hmac = crypto.createHmac('sha256', secret);
   const calculatedSignature = hmac.update(message).digest('base64');

   if (signature !== calculatedSignature) {
      return res.status(401).send('Unauthorized Request');
   }

   // 페이로드 처리 로직
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

   if (eventType === 'RightToErasureRequest'){
      const userId = payloadBody['EventPayload']['UserId'];
      const gameIds = payloadBody['EventPayload']['GameIds'];

      console.log(`페이로드 데이터: UserId=${userId} 및 GameIds=${gameIds}`);
      // 데이터 저장소에 PII를 저장하는 경우, UserId와 GameIds를 사용하여 정보 삭제
   }

   return res.json({ message: '메시지를 성공적으로 처리했습니다.' });
});

app.listen(8080, function () {
   console.log('서버 시작됨');
});