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.

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

Authentication

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

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

Authentication

Required OAuth Scope: channel:read:subscriptions

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

Authentication

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

Authentication

Required Query String Parameters

Example hub.Topic URL

Example Notification Payloads