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

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

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.

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

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

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

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

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.

Webhooks Reference

Subscribe To/Unsubscribe From Events

Authentication

URL

JSON Body Parameters

Topic: User Follows

hub.topic URL

Required Query Parameters

Example hub.topic URLs

Example Notification Payload

Topic: Stream Changed

hub.topic URL

Required Query 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

Authentication

Required Query Parameter

Example hub.topic URL

Example Notification Payload

Topic: Extension Transaction Created

Hub Topic URL

Authentication

Authorization

Required Query Parameters

Return Values

Example hub.topic URL

Example Notification Payload

Topic: Moderator Change Events

Hub Topic URLs

Required Query String Parameter

Optional Query Parameter

Use Cases

Example Notification Payload

Topic: Channel Ban Change Events

Hub Topic URLs

Required Query String Parameter

Optional Query Parameter

Use Cases

Example Notification Payload

Topic: Subscription Events

Hub Topic URL

Authentication

Required Query Parameters

Optional Query Parameters

Example hub.Topic URL

Example Notification Payloads