Webhooks Reference
Just getting started with Twitch webhooks? Try using EventSub, Twitch’s transport-neutral events solution that makes subscribing to events easier than ever.
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.
When you subscribe to a webhook, if the parameters are supplied you receive an immediate 202 Accepted
response, with an empty body. After this, we will make a call to your callback to verify your subscription; see the Webhooks Guide for information on how to implement your callback.
Also see the Get Webhooks Subscriptions endpoint.
Note: Subscription requests affect rate limits in the Twitch API.
Authentication
All topics require an authorization token. Authorization requirements are based on the hub.topic
supplied, see the reference for each topic.
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. |
Yes |
hub.lease_seconds |
integer | Number of seconds until the subscription expires. Default: 0. Maximum: 864000. Should be specified to a value greater than 0 otherwise subscriptions will expire before any useful notifications can be sent. |
Yes |
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 Parameters
The first
parameter must be specified, along with from_id
and/or to_id
.
Name | Type | Description |
---|---|---|
first |
integer | Must be 1. |
from_id |
integer | Specifies the user who starts following someone. |
to_id |
integer | 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 Parameter
Name | Type | Description |
---|---|---|
user_id |
integer | 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": "3d141868-46ed-4ef8-cd09-1fbb4f845355",
"user_id": "56145452",
"user_login": "testBroadcaster",
"user_name": "testBroadcaster",
"game_id": "509658",
"game_name": "Just Chatting",
"type": "live",
"title": "Example title from the CLI!",
"viewer_count": 9848,
"started_at": "2021-03-20T03:18:50Z",
"language": "en",
"thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_twitch_user-{width}x{height}.jpg",
"tag_ids": []
}
]
}
Topic: User Changed
Notifies when a user changes information about his/her profile. The response mimics the Get Users endpoint. This web hook requires the user:read:email
OAuth scope to get notifications of email changes.
hub.topic URL
https://api.twitch.tv/helix/users
Authentication
Token must have the user:read:email
scope for the user in question
Required Query Parameter
Name | Type | Description |
---|---|---|
id | integer | 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: Extension Transaction Created
Sends a notification when a new transaction is created for an extension. The response mimics the Get Extension Transactions endpoint.
Hub Topic URL
https://api.twitch.tv/helix/extensions/transactions
Authentication
App Access Token
Authorization
OAuth Token Client ID must match Extension Client ID.
Required Query Parameters
Parameter | Type | Description |
extension_id |
string | ID of the extension to listen to for transactions. Maximum: 1 |
first |
integer | Must be 1. |
Example hub.topic URL
Extension d1dp7kdgsq3yg4ddyyel9mz5jebvoo creates a new transaction:
https://api.twitch.tv/helix/extensions/transactions?extension_id=d1dp7kdgsq3yg4ddyyel9mz5jebvoo&first=1
Example Notification Payload
The notification payload from a web hook will always be the same as the payload from the API endpoint on which the web hook relies.
{
"data": [
{
"broadcaster_id": "23829576",
"broadcaster_name": "skeltonath",
"id": "2dfe47d0-80e1-4bc6-90e6-0536f4dfedcd",
"product_data": {
"cost": {
"amount": 100,
"type": "bits"
},
"broadcast": false,
"displayName": "Test Item",
"domain": "twitch.ext.d1dp7kdgsq3yg4ddyyel9mz5jebvoo",
"expiration": "",
"inDevelopment": true,
"sku": "testItem"
},
"product_type": "BITS_IN_EXTENSION",
"timestamp": "2019-04-04T21:37:19Z",
"user_id": "132996918",
"user_name": "skeltest"
}
]
}
Topic: Moderator Change Events
Notifies when a broadcaster adds or removes moderators.
Hub Topic URL
https://api.twitch.tv/helix/moderation/moderators/events
Required Query Parameters
Name | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token. |
first |
integer | Must be 1. |
Optional Query Parameter
Name | Type | Description |
user_id |
integer | Specifies the user ID of the moderator added or removed. |
Example hub.topic URLs
- Broadcaster aan22209 adds or removes any moderators:
https://api.twitch.tv/helix/moderation/moderators/events?broadcaster_id=198704263&first=1
- Broadcaster aan22209 adds or removes user glowillig as a moderator:
https://api.twitch.tv/helix/moderation/moderators/events?broadcaster_id=1&first=1&user_id=2
Example Notification Payload
Notification payload from a webhook will always be the same as the payload from the API endpoint on which the webhook relies.
{
"data": [
{
"id": "1IVKZGWSqf45QIgf6WFKtYpd0Or",
"event_type": "moderation.moderator.add",
"event_timestamp": "2019-03-15T19:32:58Z",
"version": "v1",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_name": "aan22209",
"user_id": "423374343",
"user_name": "glowillig"
}
}
]
}
Topic: Channel Ban Change Events
Notifies when a broadcaster bans or un-bans people in their channel.
Hub Topic URL
https://api.twitch.tv/helix/moderation/banned/events
Required Query Parameters
Name | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token. |
first |
integer | Must be 1. |
Optional Query Parameter
Name | Type | Description |
user_id |
integer | Specifies the user ID of the moderator added or removed. |
Use Cases
- Broadcaster aan22209 bans anyone in their channel:
https://api.twitch.tv/helix/moderation/banned/events?broadcaster_id=198704263&first=1
- Broadcaster aan22209 bans or unbans user glowillig in their channel:
https://api.twitch.tv/helix/moderation/banned/events?broadcaster_id=198704263&first=1&user_id=423374343
Example Notification Payload
Notification payload from a webhook will always be the same as the payload from the API endpoint on which the webhook relies.
{
"data": [
{
"id": "b0809075-c618-ee8e-705b-b1d5dcbdf9ee",
"event_type": "moderation.user.ban",
"event_timestamp": "2021-03-20T03:22:49Z",
"version": "v1",
"event_data": {
"broadcaster_id": "10019343",
"broadcaster_login": "testBroadcaster",
"broadcaster_name": "testBroadcaster",
"user_id": "34304448",
"user_login": "testFromUser",
"user_name": "testFromUser",
"expires_at": "2021-03-20T04:22:49Z"
}
}
]
}
Topic: Subscription Events
This webhook notifies you when:
- A payment has been processed for a subscription or unsubscription.
- A user who is subscribed to a broadcaster notifies the broadcaster of their subscription in the chat.
Warning: The data returned from this topic may be unreliable. If you need notifications for new channel subscriptions, consider using EventSub’s
channel.subscribe
subscription type for channel subscribe events. Learn more about EventSub.
Hub Topic URL
https://api.twitch.tv/helix/subscriptions/events
Authentication
Required OAuth Scope: channel:read:subscriptions
Required Query Parameters
Name | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token. |
first |
string | Must be 1. Must be the second parameter in the query string. |
Optional Query Parameters
Name | Type | Description |
user_id |
string | ID of the subscribed user. Currently only one user_id at a time can be queried. |
gifter_id |
string | ID of the user who gifted the sub. Returns an empty string for subs that are not gifted ( is_gift=false ).Returns 274598607 for anonymous gifts. |
gifter_name |
string | Display name of the user who gifted the sub. Returns an empty string for subs that are not gifted ( is_gift=false ). Returns AnAnonymousGfiter for anonymous gifts. |
Example hub.topic URL
https://api.twitch.tv/helix/subscriptions/events?broadcaster_id=<broadcaster_id>&first=1
Example Notification Payloads
At 2020-03-16T16:31:42 hami0315 subscribed to the broadcaster meka:
{
"data": [
{
"id": "3Wba7BrK0NQuEX9BO8emK8aHfpK",
"event_type": "subscriptions.subscribe",
"event_timestamp": "2020-03-16T16:31:42Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "158038007",
"broadcaster_name": "meka",
"is_gift": true,
"plan_name": "Channel Subscription (meka)",
"tier": "1000",
"user_id": "505037911",
"user_name": "hami0315",
"gifter_id": "156900877",
"gifter_name": "baxter4343"
}
}
]
}
At 2019-02-03T08:14:19 dallas notified broadcaster Birdman616 of their subscription in chat:
{
"data": [
{
"id": "1Gf161qjQtk0mOMD4VeIMjTGPUk",
"event_type": "subscriptions.notification",
"event_timestamp": "2019-02-03T08:14:19Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "113627897",
"broadcaster_name": "Birdman616",
"is_gift": true,
"plan_name": "Channel Subscription (Birdman616)",
"tier": "1000",
"user_id": "44322889",
"user_name": "dallas",
"message": "You are the best"
}
}
]
}
Note: plan_name
and tier
will always be empty fields for unsubscribe.
Topic: Hype Train Event
Notifies when a hype train progression occurs; e.g., a viewer subs, gifts, or uses Bits that kicks off or contributes towards a Hype Train. The response mimics the Get Hype Train Event endpoint.
hub.topic URL
https://api.twitch.tv/helix/hypetrain/events
Authentication
Required OAuth Scope: channel:read:hype_train
Required Query Parameters
Name | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token. |
Example hub.topic URL
https://api.twitch.tv/helix/hypetrain/events?broadcaster_id=<broadcaster_id>&first=1
Example Notification Payload
At 2020-04-24T20:07:24 user with id 134247454 contributed 200 bits towards the progression of the Hype Train on broadcaster with id 270954519:
{
"data": [
{
"id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
"event_type": "hypetrain.progression",
"event_timestamp": "2021-03-20T03:26:24Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "270954519",
"cooldown_end_time": "2021-03-20T03:26:24Z",
"expires_at": "2021-03-20T03:26:24Z",
"goal": 1800,
"id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
"last_contribution": {
"total": 200,
"type": "subscription",
"user": "134247454"
},
"level": 2,
"started_at": "2021-03-20T03:26:24Z",
"top_contributions": [
{
"total": 600,
"type": "bits",
"user": "134247450"
}
],
"total": 600
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
}
}