Twitch Eventsub

Previous to Start

안녕하세요. 이번 글은 Twitch에서 공식 제공하는 문서인 Handling Webhook Events를 참고하여 작성하였습니다.
지금보니 어떤 문서들보다 상세하게 잘 작성되어있는편이지만, 처음에 사용하고자 했을때 헤매었던 경험이 있어 다른사람들에게 도움이 되었으면 바램으로 간단히 Guide문서를 작성해보게되었습니다.

인증에 대한 방법은 따로 기술하지않았습니다. 추후에 기회가 된다면 기술할 예정입니다.

Overview

Event Subscription은 Twitch에서 발생한 Event를 구독할 수 있는 기능을 말합니다.
여러가지의 형태들의 Event들이 존재합니다.
이 중에서 EventSub을 통해 구독받기 원하는 Event를 Twitch 서버에 등록 할 수 있습니다.
등록해 두었던 Event가 트위치에서 발생하면 Application에 알림을 전송해 줍니다.
예를 들면 아래 종류의 notification을 전달받을 수 있습니다.

스트리머가 온라인 상태일때
스트리머의 새로운 follower가 생겼을때
스트리머의 새로운 구독자가 생겼을때
시청자가 채널 응원할때
시청자가 포인트를 기부했을때?

Twitch는 전송하는데 2가지 방식을 지원합니다.

Webhook
WebSocket

이 문서에서 설명하고자 하는 방식은 Webhook에 해당됩니다.

Required 3 API

Event Subscription을 사용하여 Event를 수신받고 싶다면 3가지 API(Callback)이 필요로 합니다.
이 Callback들은 무조건 SSL을 사용해야하며, 443 port를 사용합니다.

Request Header에 Twitch-Eventsub-Message-Type가 포함되는데, 아래의 3가지 Notification Type을 Value로 가질 수 있습니다.

webhook_callback-verification : Callback으로 등록한 Event Handler가 구독 요청한 사람의 소유인지 증명하는데 사용합니다. Event 구독을 하면, 처음으로 수신받는 Event 입니다.
notification : Event 데이터를 포함하고 있습니다. 실제로 Event를 처리하는 부분에 해당합니다.
revocation : 어떤 사유로, Twitch 서버에서 구독을 취소하게 되면 사용합니다. 이유를 포함하게 됩니다.

위 3개 Type의 Request가 유입되면, 몇초내에 응답해주어야합니다.
오랜 시간이 걸리면 Timeout으로 처리합니다. 짧은 시간안에 많은 실패가 발생한다면, Subscription 상태는 notification_failures_exceeded 으로 바뀌고 Twitch는 Event Subscription을 해지할 것입니다.

만약 서버에서 빠른 시간안에 처리가 불가능하다면, 이벤트를 임시저장소에 저장하거나 2XX로 응답한후 처리하는것을 고려해야합니다.

Common (Verifying the Event Message)

핸들러에게 전송된 메시지로 어떤 작업을 하기 전에, 악의를 가진사람이 메시를 전송한 것일수도 있으므로 해당 메시지가 Twitch에서 보낸 것인지 검증해야 합니다.
이벤트에 구독할때 이벤트에 Secret을 포함하게 되어있습니다. Twitch에서는 HMAC-SHA256(해시 기반 메시지 인증 코드) 서명을 생성할 때 Secret을 키로 사용합니다.
Twitch는 Twitch-Eventsub-Message-Signature 요청 헤더에서 핸들러에게 HMAC 서명을 전달하여, 인증합니다.

Secret과 Twitch-Eventsub-Message-Id 헤더, Twitch-Eventsub-Message-Timestamp 헤더, Request Body의 값을 연결한 메시지를 사용하여 HMAC 서명을 생성합니다.(순서가 중요합니다)
Twitch-Eventsub-Message-Signature 헤더에 Twitch가 전송한 HMAC과 내가 만든 HMAC을 비교합니다.
서명이 일치하지 않으면 4XX 상태 코드를 반환해야합니다.

아래는 Twitch에서 공식적으로 제공한 서명 생성코드 예제입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


const crypto = require('crypto')

// Notification request headers
const TWITCH_MESSAGE_ID = 'Twitch-Eventsub-Message-Id'.toLowerCase();
const TWITCH_MESSAGE_TIMESTAMP = 'Twitch-Eventsub-Message-Timestamp'.toLowerCase();
const TWITCH_MESSAGE_SIGNATURE = 'Twitch-Eventsub-Message-Signature'.toLowerCase();

// Prepend this string to the HMAC that's created from the message
const HMAC_PREFIX = 'sha256=';

app.use(express.raw({          // Need the raw message body for signature verification
    type: 'application/json'
})) 

. . .

    let secret = getSecret();
    let message = getHmacMessage(req);
    let hmac = HMAC_PREFIX + getHmac(secret, message);  // Signature to compare to Twitch's

    if (true === verifyMessage(hmac, req.headers[TWITCH_MESSAGE_SIGNATURE])) {
        console.log("signatures match");

        // Get JSON object from body, so you can process the message.
        let notification = JSON.parse(req.body);

        // Handle notification...
    }
    else {
        console.log('403');
        res.sendStatus(403);
    }

. . .

function getSecret() {
    // TODO: Get your secret from secure storage. This is the secret you passed 
    // when you subscribed to the event.
    return '<your secret goes here>';
}

// Build the message used to get the HMAC.
function getHmacMessage(request) {
    return (request.headers[TWITCH_MESSAGE_ID] + 
        request.headers[TWITCH_MESSAGE_TIMESTAMP] + 
        request.body);
}

// Get the HMAC.
function getHmac(secret, message) {
    return crypto.createHmac('sha256', secret)
    .update(message)
    .digest('hex');
}

// Verify whether your signature matches Twitch's signature.
function verifyMessage(hmac, verifySignature) {
    return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(verifySignature));
}

모든 Request에 대해서 이 검증작업이 수행되어야합니다. 보안상으로 중요한 이슈이기 때문에, 잘 만들어 주는게 좋습니다.

Responding to Challenge Request

이벤트를 정기구독하면 Twitch는 요청에 지정된 이벤트 핸들러를 소유하고 있는지 확인하기 위해 Authentification Challenge를 보냅니다.
챌린지 메시지는 Twitch-Eventsub-Message-Type 헤더를 webhook_callback_verification으로 설정합니다.
예를 들면 아래와 같습니다.

1

Twitch-Eventsub-Message-Type: webhook_callback_verification

요청 본문의 challenge 필드에는 응답해야 하는 challenge 값이 포함되어 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{
  "challenge": "pogchamp-kappa-360noscope-vohiyo",
  "subscription": {
    "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
    "status": "webhook_callback_verification_pending",
    "type": "channel.follow",
    "version": "1",
    "cost": 1,
    "condition": {
      "broadcaster_user_id": "12826"
    },
    "transport": {
      "method": "webhook",
      "callback": "https://example.com/webhooks/callback"
    },
    "created_at": "2019-11-16T10:11:12.634234626Z"
  }
}

응답은 200 상태 코드를 반환해야 하며, Response Header에 Content-Type: text/plain이 포함되어야 하고 Response Body는 challenge만 포함해야 합니다. 성공하면 구독이 활성화된 것입니다.
서버에서 웹 프레임워크를 사용하는 경우 웹 프레임워크가 호환되지 않는 방식으로 응답을 수정하지 않도록 주의하세요.

Processing an event

정기구독한 이벤트가 발생하면 Twitch는 이벤트 데이터가 포함된 알림 메시지를 이벤트 처리자에게 보냅니다. 알림 메시지는 Twitch-Eventsub-Message-Type 헤더를 알림으로 설정합니다.
예를 들어 Twitch-Eventsub-Message-Type: notification 로 볼 수 있습니다.

Request body에는 subscription와 event에 정보가 포함되어있습니다.
subscription.type 필드는 이벤트 유형을 식별할 수 있는 정보를 포함하고 있습니다.
event 필드에는 구독한 이벤트 타입에서 실제로 발생한 이벤트의 데이터가 포함됩니다.

아래는 예시입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


{
  "subscription": {
    "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
    "status": "enabled",
    "type": "channel.follow",
    "version": "1",
    "cost": 1,
    "condition": {
      "broadcaster_user_id": "12826"
    },
    "transport": {
      "method": "webhook",
      "callback": "https://example.com/webhooks/callback"
    },
    "created_at": "2019-11-16T10:11:12.634234626Z"
  },
  "event": {
    "user_id": "1337",
    "user_login": "awesome_user",
    "user_name": "Awesome_User",
    "broadcaster_user_id":     "12826",
    "broadcaster_user_login":  "twitch",
    "broadcaster_user_name":   "Twitch",
    "followed_at": "2020-07-15T18:16:11.17106713Z"
  }
}

응답은 2XX 상태 코드를 반환해야 합니다.

이벤트 처리에 1~2초 이상 걸리는 경우 이벤트를 임시 저장소에 쓰고 2XX로 응답한 후 알림을 처리하는 것이 좋습니다.
너무 많이 빠르게 응답하지 않으면 정기구독 상태가 notification_failures_exceeded로 변경되고 Twitch에서 구독을 취소해버립니다.

이벤트 발생시 처리하고 싶은 비지니스 로직은 이 부분에 Request를 처리하며 포함하면 됩니다.

Revoking your subscription

정기구독은 만료되지 않지만 Twitch는 정기구독을 취소할 수 있습니다. Twitch는 다음과 같은 경우에 정기구독을 취소합니다

정기구독에 언급된 유저가 더 이상 존재하지 않는 경우. 알림 상태가 user_removed로 설정된 경우.
사용자가 인증 토큰을 해지했거나 단순히 비밀번호를 변경한 경우. 알림의 상태가 authorization_revoked로 설정됩니다.
콜백이 적시에 응답하지 않은 횟수가 너무 많습니다. 알림의 상태가 알림_실패_초과로 설정됩니다.
구독한 구독 유형 및 버전이 더 이상 지원되지 않습니다. 알림의 상태가 version_removed로 설정되어 있습니다.

Twitch는 언제든지 정기구독을 취소할 수 있는 권리를 보유합니다. 해지 메시지는 Twitch-Eventsub-Message-Type 헤더를 revocation로 설정합니다.
예를 들어 아래와 같습니다.

1

Twitch-Eventsub-Message-Type: revocation

요청 본문의 status 필드에는 Twitch가 정기구독을 취소한 이유가 표시됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "subscription": {
    "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
    "status": "authorization_revoked",
    "type": "channel.follow",
    "cost": 1,
    "version": "1",
    "condition": {
      "broadcaster_user_id": "12826"
    },
    "transport": {
      "method": "webhook",
      "callback": "https://example.com/webhooks/callback"
    },
    "created_at": "2019-11-16T10:11:12.634234626Z"
  }
}

응답은 2XX 상태 코드를 반환해야 합니다.

Testing your Handler

Twitch의 명령줄 인터페이스(CLI)는 이벤트 핸들러를 테스트하는 데 사용할 수 있는 이벤트 명령을 제공합니다. 이 명령은 SSL이 필요하지 않으며, 손쉽게 테스트할 수 있습니다.

도전 이벤트(Testing Challenge events)
알림 이벤트(Testing notification events)

Testing challenge Events

이벤트에 가입하면 Twitch는 요청에 지정된 이벤트 처리자에게 webhook_callback-verification 알림 이벤트를 보내, Event Handler를 소유하고 있는지 확인합니다.
다음 CLI 예제는 Challenge Event에 대한 응답을 테스트하는 방법을 보여줍니다.
실행하기 전에 -F 플래그의 값을 핸들러를 가리키도록 변경하고 -s 플래그의 값을 비밀로 변경하세요.
비밀 플래그는 선택 사항이지만 항상 지정해야 핸들러에서 메시지가 Twitch에서 왔는지 확인하는 부분이 작동합니다.

그런 다음 터미널 창을 열고 명령을 실행합니다.

1

twitch event verify-subscription subscribe -F http://localhost:8080/eventsub/ -s 5f1a6e7cd2e7137ccf9e15b2f43fe63949eb84b1db83c1d5a867dc93429de4e4

모든 작업을 올바르게 수행했다면 출력은 다음과 같습니다.

1
2


✔ Valid response. Received challenge 5e784545-5a59-a05a-6ae6-cfaf260532f1 in body
✔ Valid status code. Received status 200

verify-subscription 하위 명령 사용에 대한 자세한 내용은 이벤트 처리기의 챌린지 응답 확인하기를 참조하세요.

Testing notification events

트리거 하위 명령을 사용하여 이벤트 핸들러에 모의 이벤트를 전송합니다. 명령의 인수는 트리거할 이벤트를 식별합니다.
실행하기 전에 -F 플래그의 값을 핸들러를 가리키도록 변경하고 -s 플래그의 값을 시크릿으로 변경하세요.
비밀 플래그는 선택 사항이지만 항상 지정해야 핸들러에서 메시지가 Twitch에서 왔는지 확인하는 부분이 작동합니다.

그런 다음 터미널 창을 열고 명령을 실행합니다.

1

twitch event trigger subscribe -F http://localhost:8080/eventsub/ -s 5f1a6e7cd2e7137ccf9e15b2f43fe63949eb84b1db83c1d5a867dc93429de4e4

Conclusion

Twtich EventSubscription을 어떻게 사용해야하는지, 어떻게 테스트해야하는지에 대해서 살펴보았습니다.
Twitch 공식문서에 잘 설명 되어있기때문에, 덧붙일 내용이 많진 않았습니다.
하지만 처음보는 사람으로서 어떤 순서로 사용하는지, 어떤 용도로 사용해야하는건지 파악하기 힘들어 정리해보았습니다. (경험이 부족한것일수도있겠지만요…)
다른 분들께 도움이 되면 좋겠습니다.

Reference

Twitch Event Subscription 공식문서 : https://dev.twitch.tv/docs/eventsub/handling-webhook-events/