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
Name | Type | Description | Required? |
---|---|---|---|
hub.callback | string | URL where notifications will be delivered. | Yes |
hub.mode | string | Type of request. Valid values: subscribe , unsubscribe . | Yes |
hub.topic | string | URL for the topic to subscribe to or unsubscribe from. topic maps to a new Twitch API endpoint. We support these topics:
| Yes |
hub.lease_seconds | int | Number 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.secret | string | Secret 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
.
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
- User 1336 follows someone:
https://api.twitch.tv/helix/users/follows?first=1&from_id=1336
- User 1337 has a new follower:
https://api.twitch.tv/helix/users/follows?first=1&to_id=1337
- User 1336 follows user 1337:
https://api.twitch.tv/helix/users/follows?first=1&from_id=1336&to_id=1337
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
Name | Type | Description |
---|---|---|
id | int | Specifies 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
Name | Type | Description |
---|---|---|
game_id | string | Specifies 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
Name | Type | Description |
---|---|---|
extension_id | string | Specifies 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