웹 후크 알림

*이 콘텐츠는 AI(베타)를 사용해 번역되었으며, 오류가 있을 수 있습니다. 이 페이지를 영어로 보려면 여기를 클릭하세요.

사용자가 경험에서 모든 이벤트를 수동으로 모니터링하고 요청하는 대신, 웹 호크를 설정하여 실시간 알림을 받을 수 있습니다. 이를 통해 알림 관리 워크플로우를 자동화하여 수동 노력 처리 알림을 줄일 수 있습니다. 이렇게 하면 알림 관리 워크플로우를 줄이면 수동 노력 처리 알림을 줄일 수 있

웹 후크 워크플로

웹 호크는 Roblox 및 제3자 메시징 도구와 같은 두 개의 다른 응용 프로그램 또는 서비스 사이에서 실시간 알림이나 데이터를 전송하는 데 사용됩니다. 전통적인 API는 클라이언트 응용 프로그램을 설정해야 하므

웹 후크를 설정하면 대상 이벤트가 발생할 때마다 Roblox는 제공하는 웹 후크 URL로 요청을 보냅니다. 웹 후크 URL은 웹 후크 전송 업로드에 포함된 데이터에 따라 요청을 대상 애플리케이션이나 사용자 지정 엔드포인트로 리디렉션합니다. 이에 포함될 수

지원되는 트리거

Roblox는 현재 다음과 같은 이벤트 트리거를 지원합니다. 알림:

  • 구독 취소됨 - 사용자가 구독을 취소하면 메시지에 구독 구독 및 구독자가 포함되어 있으며 취소 이유가 포함되어 있습니다.
  • 구독 구매 완료 - 사용자가 구독을 구매하면 구독 및 구독자가 포함된 메시지가 표시됩니다.
  • 구독 환불 - 사용자가 구독 환불을 받을 때 구독 및 구독자가 포함된 메시지가 표시됩니다.
  • 구독 갱신 완료 - 사용자가 구독을 갱신할 때 구독과 구독자가 포함된 메시지가 표시됩니다.
  • 구독 재구독 - 사용자가 구독에 재구독할 때 구독 및 구독자가 포함된 메시지가 표시됩니다.
  • “잊혀질 권리” 데이터 삭제 요청은 일반 데이터 보호 규정( GDPR )에 따라 수행됩니다.

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

크리에이터 대시보드에서 웹 호크 구성

웹 호크를 통해 알림을 받으려면 특정 이벤트에 대해 웹 호크에 구독해야 합니다. 그룹 소유 경험의 경우 그룹 소유자만 웹 호크 알림을 구성하고 받을 수 있습니다.

웹 후크를 설정하려면:

  1. 크리에이터 대시보드의 웹 호크 섹션으로 이동합니다.
  2. 클릭하십시오 웹 훅 추가 버튼.
  3. 구성 필드 완료:
    1. Webhook URL — 알림을 받고 제3자 엔터티로부터 웹 후크 URL을 수신할 위치를 지정합니다. 필요한 내용은 웹 후크 설정 을 참조하십시오.
    2. 이름 — 구성을 다른 구성과 구분하려면 사용자 정의 이름을 사용하십시오. 기본적으로 값은 Webhook URL과 동일합니다.
    3. 비밀 (옵션) — 알림을 받은 위치가 Roblox인지 확인하려면 비밀을 공급하십시오. 자세한 내용은 웹후크 보안 검사를 참조하십시오.
    4. 트리거 — 알림을 받을 이벤트의 지원 트리거 목록 에서 옵션을 선택하십시오.
  4. 클릭하십시오 변경 사항 저장 버튼을 .

Webhook URL 설정

다음 요건을 충족하면 사용자 지정 HTTP 서비스 엔드포인트를 웹 후크 URL로 설정할 수 있습니다.You can set up a custom HTTP service endpoint as your webhook URL, provided it fulfills the following requirements:

  • 요청을 처리하는 데 공개적으로 액세스해야 합니다.
  • POST 요청을 처리할 수 있습니다.
  • 5초 이내에 2XX 응답을 요청에 응답할 수 있습니다.
  • HTTPS 요청을 처리할 수 있습니다.

엔드포인트가 POST 요청을 받으면 다음을 수행할 수 있어야 합니다.

  • 포스트 메시지의 본문에 대한 알림에 대한 세부 정보를 추출합니다.
  • 알림과 이벤트 유형에 대한 특정 세부 정보가 포함된 일반적인 세부 정보가 포함된 게시 메시지의 몸을 읽습니다.Read the body of the POST message with the generic details on the notification and specific details related to the event type on the notification.

POST 요청 처리에 대한 자세한 내용은 Payload Schema를 참조하십시오.

배송 실패 재시 정책

端점 가용성 문제, 메시지 전송 시 잘못된 URL 5 번을 사용하여 지정된 URL에 도달하지 못했습니다.Roblox는 메시지를 구성된 URL로 다시 보내기 위해 고정 창 크기를 사용하여 오류가 발생했

제3자 요구 사항

제3자 도구는 일반적으로 웹 호크 URL을 설정할 때 웹 호크 요청을 수행해야 하는 요구 사항이 있습니다. 이 요구 사항은 대상 도구의 지원 또는 문서화 사이트에서 키워드 "웹 호크"를 검색하여 찾을 수 있습니다. 웹 호크를 지원하는 세 가지 주요 제3자 도구는 팔로잉같습니다.

웹 호크 테스트

구성한 웹 훅이 크리에이터 대시보드에서 알림을 성공적으로 받을 수 있는지 테스트할 수 있습니다.

  1. 웹 호크 구성 페이지로 이동합니다.

  2. 구성된 웹 훅 목록에서 테스트할 웹 후크를 선택하십시오.

  3. 대상 웹 훅 옆에 있는 연필 아이콘을 클릭하십시오.

    The pencil icon next to an example webhook

  4. 클릭하십시오 테스트 응답 버튼.

이제 시스템은 알림을 보내는 입력SampleNotification에 사용자 ID가 포함된 알림을 보냅니다. 다음 예시 스키마에서 볼 수 있듯이:

SampleNotification 스키마
Body: {

  "NotificationId": "string",

  "EventType": "SampleNotification",

  "EventTime": "2023-12-30T16:24:24.2118874Z", // 형식: ISO 8601 시간 표시

  "EventPayload": {

    "UserId": 1 // 형식: 길게

  }

}

웹 후크를 제3자 서비스와 통합하는 경우 웹 후크에서 알림을 성공적으로 수신할 수 있는지 확인하기 위해 제3자 URL을 사용하여 테스트할 수 있습니다. 웹 후크를 구성할 때 비밀을 제공하면 웹 후크 로직을 테스트하는 데 사용할 수 있

웹 후크 보안 검증

서버에 대한 전송 작업을 구성한 후 첫 번째 작업은 엔드포인트에 전송된 모든 작업을 수신하기 시작합니다. 웹 호크 구성 시 비밀을 설정하면 Roblox는 모든 웹 호크 알림에 roblox-signature

Signature Format with Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

웹 후크에 대한 비밀이 없으면 받는 서명에는 알림이 발송될 때의 시간 戳만 포함됩니다.If you don't have a secret for your webhook, the signature you receive only contains the timestamp value on when the notification is sent:

Signature Format without Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>"

서명을 확인하려면:

  1. 시간 표시자 및 서명 값을 추출합니다. 웹 호크에 대한 모든 서명은 이 두 값 다음에 있는 CSV 문자열과 같은 형식을 공유합니다.

    • t : 알림이 전송될 때의 시간 戳 값입니다.
    • v1 : 크리에이터 대시보드 구성에 제공된 시그니처 값을 사용하여 서명 값을 생성합니다. split() 함수를 사용하여 이 두 값을 추출할 수 있으며, 이 경우 문자열을 기반으로 하는 구분기는 ,입니다.

  2. 다음을 사용하여 roblox-signature 의 기본 문자열을 다시 만듭니다.

    1. 문자열 형식의 시간 표시자.
    2. 기간 문자 . .
    3. 요청 바디의 JSON 신체.

  3. 키와 기본 문자열을 생성하는 단계 2 동안 정의한 비밀을 사용하여 해시 기반 메시지 인증 코드(HMAC)를 계산하십시오. 결과를 기반 64 형식으로 변환하여 예상 서명을 확인하십시오.

  4. 추출된 서명 값을 예상 서명 값과 비교하십시오. 서명을 올바르게 생성했다면 값이 동일해야 합니다.

  5. (옵션) 재생 공격을 방지하려면 공격자가 데이터를 수신하고 다시 전송하여 사용자 권한을 얻거나 악의적인 작업을 수행하려는 경우 추출된 타임스탬프 값과 현재 타임스탬프를 비교하여 합법적인 시간 제한 내에 있는지 확인하는 것이 좋습니다. 예를 들어, 10분 창은 일

Payload 스키마

웹 훅의 대상 이벤트가 트리거되면 웹 훅 URL에 대한 요청을 보내고, 이벤트 속 정보를 포함합니다. 모든 요청 웹 훅은 고정된 필드와 변수 필드가 포함된 정보를 포함하는 동일한 스키마를 공유합니다. 이렇게 하면 데이터를 전송하는 웹 훅이 구조적이

고정된 페이로드 스키마 필드 는 모든 웹 호크 요청에 대해 일관성을 유지하는 데 도움이 될 수 있습니다. 다음 필드가 사용 가능합니다.

  1. NotificationId , string : 각 알림을 보낸 고유한 식별자. 동일한 NotificationId 를 두 번 받으면 중복으로 간주됩니다.
  2. EventType , string : 알림이 발생한 이벤트 유형을 나타냅니다.
  3. EventTime , timestamp : 이벤트가 발생한 시간을 나타내는 정확한 시간 표시자입니다.

변수 적재 스키마 필드는 웹 호크에 다양한 종류의 이벤트를 수용할 수 있도록 유연성을 제공합니다. 여기에는 다음이 포함됩니다.

  1. EventPayload , object : 웹 호크를 트리거한 EventType 에 대한 정보를 포함합니다. 0> Eventpayload 구조는 이벤트 유형에 따라 변경됩니다.

다음 예시에서는 Right To Erasure Request 이벤트의 페이로드 스키마를 보여줍니다.

맞춤형 삭제 요청에 대한 예시 스키마
Body:{



   "NotificationId": "string",



   "EventType": "RightToErasureRequest",



   "EventTime": "2023-12-30T16:24:24.2118874Z",



   "EventPayload": {



      "UserId": 1, // 형식: 길게



      "GameIds": [ // 형식: 길이 배열



         1234, 2345



      ]



   }



}

알림 처리

사용자의 개인 식별 정보(PII)를 저장하는 경우, 예를 들어 사용자의 사용자 ID(User ID)와 같

웹 호크 서버를 제3자 도구가 아닌 사용자 지정 엔드포인트로 사용하는 경우, 웹 호크 전송에서 데이터 주제를 삭제하고 자신의 자동화 솔루션을 빌드할 수 있습니다. 다음 코드 샘플은 예시 솔루션을 제공하고 요청이 Roblox에서 온 것을 확인하여 재생 공격을 방지하는 방법

Extracting PII from Payload
const crypto = require('crypto')

const express = require('express');

let app = express();

app.use(express.json());

app.use(express.urlencoded({ extended: true }));

// This is a sample only code

app.all('/*', function (req, res) {

   console.log('-------- New Request Seen -------');

   // 1. Extract the timestamp and signature

   const shared_secret = '<Your secret>' // This can be set as an environment variable

   const hmac = crypto.createHmac('sha256', shared_secret)

   const roblox_signature_header = req.headers['roblox-signature'].split(',')

   // 'roblox-signature' is present in all requests:

   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.

   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='

   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);

   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));

   // 2. Prevent Replay attack: 300 seconds window

   const request_timestamp_ms = timestamp * 1000;

   const window_time_ms = 300 * 1000

   const oldest_timestamp_allowed = Date.now() - window_time_ms;

   if (request_timestamp_ms < oldest_timestamp_allowed) {

      res.status(403).send('Expired Request')

   }

   // 3. Validate Signature

   if (extracted_signature !== undefined) {

      const signature_v1 = extracted_signature.substring(3);

      const message = `${timestamp}.${JSON.stringify(req.body)}`

      const base64_signature = hmac.update(message).digest('base64')

      if (signature_v1 !== base64_signature) {

         res.status(401).send('Unauthorized Request')

      }

   }

   // 4. Your logic to handle payload

   const payloadBody = req.body

   const eventType = payloadBody['EventType']

   if (eventType === 'RightToErasureRequest'){

      const userId = payloadBody['EventPayload']['UserId']

      const gameIds = payloadBody['EventPayload']['GameIds']

      const gameIdString = gameIds.toString()

      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)

      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.

   }

   // 5. Return Response

   res.json({ message: 'Processed the message Successfully' });

})

app.listen(8080, function () {

   console.log('This is a Sample application')

})