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.

Web hook response payloads mimic their respective New Twitch API endpoint responses (with minor omissions for unnecessary fields). That is, a call to a web hook 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.
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.  

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 web hook 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: Extension Transaction Created

Sends a notification when a new transaction is created for an extension.

Hub Topic URL

https://api.twitch.tv/helix/extensions/transactions?extension_id=<extension_id>&first=1

Authentication

App Access OAuth Token

Authorization

OAuth Token Client ID must match Extension Client ID.

Required Query String Parameters

Note: All parameters, required and optional, must be used in alphabetical order.

Parameter Type Description
extension_id string ID of the extension to listen to for transactions. Maximum: 1
first integer Must be 1.

Return Values

Parameter Type Description
data array Array of requested transactions.
   id string Unique identifier of the Bits in Extensions Transaction.
   timestamp string UTC timestamp when this transaction occurred.
   broadcaster_id string Twitch User ID of the channel the transaction occurred on.
broadcaster_name string Twitch Display Name of the broadcaster.
   user_id string Twitch User ID of the user who generated the transaction.
   user_name string Twitch Display Name of the user who generated the transaction.
   product_type string Enum of the product type. Currently only BITS_IN_EXTENSION.
   product_data object JSON Object representing the product acquired, as it looked at the time of the transaction.
      domain string Set this field to twitch.ext + your extension ID.
      broadcast Boolean Flag that denotes whether or not the data was sent over the extension pubsub to all instances of the extension.
      expiration string Always empty since only unexpired products can be purchased.
      sku string Unique identifier for the product across the extension.
      cost object JSON Object representing the cost to acquire the product.
         amount integer Number of Bits required to acquire the product.
         type enum Always the string “Bits”.
      displayName string Display Name of the product.
      inDevelopment Boolean Flag used to indicate if the product is in development. Either true or false.

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 URLs

  1. https://api.twitch.tv/helix/moderation/moderators/events?broadcaster_id=<broadcaster_id>&first=1
    
  2. https://api.twitch.tv/helix/moderation/moderators/events?broadcaster_id=<broadcaster_id>&first=1&user_id=<user_id>
    

Required Query String Parameter

Note that all parameters, required and optional, must be used in alphabetical order.

Name Type Description
first integer Must be 1.

Optional Query String Parameter

Note that all parameters, required and optional, must be used in alphabetical order.

Name Type Description
user_id int Specifies the user ID of the moderator added or removed.

Use Cases

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 URLs

  1. https://api.twitch.tv/helix/moderation/banned/events?broadcaster_id=<broadcaster_id>&first=1
    
  2. https://api.twitch.tv/helix/moderation/banned/events?broadcaster_id=<broadcaster_id>&first=1&user_id=<user_id>
    

Required Query String Parameter

Note that all parameters, required and optional, must be used in alphabetical order.

Name Type Description
first integer Must be 1.

Optional Query String Parameter

Note that all parameters, required and optional, must be used in alphabetical order.

Name Type Description
user_id int Specifies the user ID of the moderator added or removed.

Use Cases

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.user.ban",
            "event_timestamp": "2019-03-15T19:32:58Z",
            "version": "v1",
            "event_data": {
                "broadcaster_id": "198704263",
                "broadcaster_name": "aan22209",
                "user_id": "423374343",
                "user_name": "glowillig"

    ],
}

Topic: Subscription Events

This webhook notifies you when:

Hub Topic URL

https://api.twitch.tv/helix/subscriptions/events

Required Query String Parameters

Name Type Description
broadcaster_id string User ID of the broadcaster. Must match the User ID in the Bearer token.
Must be the first parameter in the query string.
first string Must be 1.
Must be the second parameter in the query string.

Optional Query String Parameter

Name Type Description
user_id string ID of the subscribed user. Currently only one user_id at a time can be queried.

Example hub.Topic URL

https://api.twitch.tv/helix/subscriptions/events?broadcaster_id=113627897&first=1

Example Notification Payloads

At 2019-02-03T08:14:19 dallas subscribed to the broadcaster Birdman616:

​​​​​​​{
  "data": [

      "id": "1Gf161qjQtk0mOMD4VeIMjTGPUk",
      "event_type": "subscriptions.subscribe",
      "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" }
            ]
}

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.