Contents

Webhooks Reference

Starting on April 30, 2020, all Helix endpoints will require OAuth and matching client IDs. See this announcement for more details. Documentation will be updated as these requirements go into effect.

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 supplied are 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

Varies based on the hub.topic supplied, see the reference for each topic below.

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

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": "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

Authentication

Token must have the user:read:email scope for the user in question

Required Query Parameter

NameTypeDescription
idintegerSpecifies 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 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 Parameter

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

Name Type Description
user_id integer 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 Parameter

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

Name Type Description
user_id integer 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

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.
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 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=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.