Contents

Webhooks Reference 

Endpoint Description
Subscribe To/Unsubscribe From Events Subscribe to or unsubscribe from events for a specified topic.

Subscribe To/Unsubscribe From Events

Subscribe to or unsubscribe from events for a specified topic.

Webhook response payloads mimic their respective New Twitch API endpoint responses (with minor omissions for unnecessary fields). That is, a call to a webhook returns in its payload the same data as a call to the corresponding endpoint in the new Twitch API.

Also see the Get Webhooks Subscriptions endpoint.

Note: Subscription requests affect rate limits in the new Twitch API.

Authentication

None

URL

POST https://api.twitch.tv/helix/webhooks/hub

JSON Body Parameters

NameTypeDescriptionRequired?
hub.callbackstringURL where notifications will be delivered.Yes
hub.modestringType of request. Valid values: subscribe, unsubscribe.Yes
hub.topicstringURL for the topic to subscribe to or unsubscribe from. topic maps to a new Twitch API endpoint. We support these topics:
  • User Follows — Notifies when a follows event occurs.
  • Stream Changed — Notifies when a stream changes; e.g., stream goes online or offline, the stream title changes, or the game changes.
  • User Changed — Notifies when a user changes information about his/her profile.
  • Game Analytics — Notifies when a new analytics report (CSV file) is available for a game.
  • Extension Analytics — Notifies when a new analytics report (CSV file) is available for an extension.
Yes
hub.lease_secondsintNumber of seconds until the subscription expires. Default: 0. Maximum: 864000.

The default (0) allows you to test the subscription-creation workflow without creating any subscriptions (since they expire immediately). After testing, to actually create subscriptions, you must specify a larger value.		No
hub.secretstringSecret used to sign notification payloads. The X-Hub-Signature header is generated by sha256(secret, notification_bytes). We strongly encourage you to use this, so your application can verify that notifications are genuine.No

Topic: User Follows

Notifies when a follows event occurs. The response mimics the Get Users Follows endpoint.

hub.topic URL

https://api.twitch.tv/helix/users/follows

Required Query String Parameters

The first parameter must be specified, along with from_id and/or to_id.  Note that query parameters must be in alphabetical order.

Name Type Description
first int Must be 1.
from_id int Specifies the user who starts following someone.
to_id int Specifies the user who has a new follower.

Example hub.topic URLs

Example Notification Payload

{
   "data":
      [{
         "from_id":"1336",
         "from_name":"ebi",
         "to_id":"1337",
         "to_name":"oliver0823nagy",
         "followed_at": "2017-08-22T22:55:24Z"
      }]
}

Topic: Stream Changed

Notifies when a stream changes; e.g., stream goes online or offline, the stream title changes, or the game changes. The response mimics the Get Streams endpoint.

hub.topic URL

https://api.twitch.tv/helix/streams

Required Query String Parameter

Name Type Description
user_id int Specifies the user whose stream is monitored.

Example hub.topic URL

User 5678’s stream changes: https://api.twitch.tv/helix/streams?user_id=5678

Example Notification Payload for Stream Offline Event

{
   "data": []
}

Example Notification Payload for Other Stream Change Events

{
   "data":
      [{
         "id":"0123456789",
         "user_id":"5678",
         "user_name":"wjdtkdqhs",
         "game_id":"21779",
         "community_ids":[],
         "type":"live",
         "title":"Best Stream Ever",
         "viewer_count":417,
         "started_at":"2017-12-01T10:09:45Z",
         "language":"en",
         "thumbnail_url":"https://link/to/thumbnail.jpg"
      }]
}

Topic: User Changed

Notifies when a user changes information about his/her profile. The response mimics the Get Users endpoint. This webhook requires the user:read:email OAuth scope, to get notifications of email changes.

hub.topic URL

https://api.twitch.tv/helix/users

Required Query String Parameter

NameTypeDescription
idintSpecifies the user whose data is monitored.

Example hub.topic URL

User 1234’s profile data changes: https://api.twitch.tv/helix/users?id=1234

Example Notification Payload

{
   "data":
      [{
         "id": "1234",
         "login": "1234login",
         "display_name": "hiiam1234",
         "type": "staff",
         "broadcaster_type": "",
         "description": "1234 is me",
         "profile_image_url": "https://link/to/pic/1234.jpg",
         "offline_image_url": "https://link/to/offline_pic/1234_off.jpg",
         "view_count": 3455
      }]
}

Topic: Game Analytics

Notifies when a new analytics report (CSV file) is available for a game. The response mimics the Get Game Analytics endpoint. This webhook requires the analytics:read:games OAuth scope.

hub.topic URL

https://api.twitch.tv/helix/analytics/games

Required Query String Parameter

NameTypeDescription
game_idstringSpecifies the game whose report data is provided.

Example hub.topic URL

Get notified of analytics data for game 1234: https://api.twitch.tv/helix/analytics?game_id=1234

Example Notification Payload

{
  "data": [
    {
      "type": "overview_v1",
      "game_id": "1234",
      "URL": "https://twitch-report-signed-url-v1-1234.csv",
      "date_range": {
        "started_at": "2018-01-01T00:00:00Z",
        "ended_at": "2018-02-01T00:00:00Z"
      }
    },
    {
      "type": "overview_v2",
      "game_id": "1234",
      "URL": "https://twitch-report-signed-url-v2-1234.csv",
      "date_range": {
        "started_at": "2018-01-01T00:00:00Z",
        "ended_at": "2018-02-01T00:00:00Z"
      }
    }
  ]
}

Topic: Extension Analytics

Notifies when a new analytics report (CSV file) is available for an extension. The response mimics the Get Extension Analytics endpoint. This webhook requires the analytics:read:extensions OAuth scope.

hub.topic URL

https://api.twitch.tv/helix/analytics/extensions

Required Query String Parameter

NameTypeDescription
extension_idstringSpecifies the extension whose report data is provided. This is the client ID value assigned to the extension when it is created.

Example hub.topic URL

Get notified of analytics data for extension abcd: https://api.twitch.tv/helix/analytics?extension_id=abcd

Example Notification Payload

{
  "data": [
    {
      "type": "overview_v1",
      "extension_id": "abdc",
      "URL": "https://twitch-report-signed-url-v1-abdc.csv"
      "date_range": {
        "ended_at": "2019-01-05T00:00:00Z",
        "started_at": "2018-10-07T00:00:00Z"
      },
    },
    {
      "type": "overview_v2",
      "extension_id": "abdc",
      "URL": "https://twitch-report-signed-url-v2-abdc.csv"
      "date_range": {
        "ended_at": "2019-01-04T00:00:00Z",
        "started_at": "2018-01-31T00:00:00Z"
      },
    }
  ]
}

Example Of Webhook Flow

Request

This subscribes to the event, user 1337 has a new follower.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-X POST -d '{"hub.mode":"subscribe",
"hub.topic":"https://api.twitch.tv/helix/users/follows?first=1&to_id=1337",
"hub.callback":"https://yourwebsite.com/path/to/callback/handler",
"hub.lease_seconds":"864000",
"hub.secret":"s3cRe7"}' \
https://api.twitch.tv/helix/webhooks/hub

Response

202 Accepted

Subscription Verify Request (from Twitch to Client)

GET https://yourwebsite.com/path/to/callback/handler? \
hub.mode=subscribe& \
hub.topic=https://api.twitch.tv/helix/users/follows?first=1&to_id=1337& \
hub.lease_seconds=864000& \
hub.challenge=HzSGH_h04Cgl6VbDJm7IyXSNSlrhaLvBi9eft3bw

Subscription Verify Response

HzSGH_h04Cgl6VbDJm7IyXSNSlrhaLvBi9eft3bw

Subscription Denied Request (from Twitch to Client)

GET https://yourwebsite.com/path/to/callback/handler? \
hub.mode=denied& \
hub.topic=https://api.twitch.tv/helix/users/follows?first=1&to_id=1337& \
hub.reason=unauthorized

Subscription Denied Response

200 OK
Docs Status Support Showcase Blog