Webhooks Reference

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

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

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

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

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

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

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 URLs

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

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

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

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.

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.

Webhooks Reference

Subscribe To/Unsubscribe From Events

Authentication

URL

JSON Body Parameters

Topic: User Follows

hub.topic URL

Required Query String Parameters

Example hub.topic URLs

Example Notification Payload

Topic: Stream Changed

hub.topic URL

Required Query String Parameter

Example hub.topic URL

Example Notification Payload for Stream Offline Event

Example Notification Payload for Other Stream Change Events

Topic: User Changed

hub.topic URL

Required Query String Parameter

Example hub.topic URL

Example Notification Payload

Topic: Extension Transaction Created

Hub Topic URL

Authentication

Authorization

Required Query String Parameters

Return Values

Example hub.topic URL

Example Notification Payload

Topic: Moderator Change Events

Hub Topic URLs

Required Query String Parameter

Optional Query String Parameter

Use Cases

Example Notification Payload

Topic: Channel Ban Change Events

Hub Topic URLs

Required Query String Parameter

Optional Query String Parameter

Use Cases

Example Notification Payload

Topic: Subscription Events

Hub Topic URL

Required Query String Parameters

Example hub.Topic URL

Example Notification Payloads