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.

When you subscribe to a webhook, if the parameters are supplied 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

All topics require an authorization token. Authorization requirements are based on the hub.topic supplied, see the reference for each topic.

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. The response mimics the Get Extension Transactions endpoint.

Hub Topic URL

https://api.twitch.tv/helix/extensions/transactions

Authentication

App Access Token

Authorization

OAuth Token Client ID must match Extension Client ID.

Required Query Parameters

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

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 URL

https://api.twitch.tv/helix/moderation/moderators/events

Required Query Parameters

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

Optional Query Parameter

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

Example hub.topic URLs

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 URL

https://api.twitch.tv/helix/moderation/banned/events

Required Query Parameters

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

Optional Query Parameter

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.
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=<broadcaster_id>&first=1

Example Notification Payloads

At 2020-03-16T16:31:42 hami0315 subscribed to the broadcaster meka:

{
  "data": [
    {
      "id": "3Wba7BrK0NQuEX9BO8emK8aHfpK",
      "event_type": "subscriptions.subscribe",
      "event_timestamp": "2020-03-16T16:31:42Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "158038007",
        "broadcaster_name": "meka",
        "is_gift": true,
        "plan_name": "Channel Subscription (meka)",
        "tier": "1000",
        "user_id": "505037911",
        "user_name": "hami0315",
        "gifter_id": "156900877",
        "gifter_name": "baxter4343"
      }
    }
  ]
}

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. 

Topic: Hype Train Event

Notifies when a hype train progression occurs; e.g., a viewer subs, gifts, or uses Bits that kicks off or contributes towards a Hype Train. The response mimics the Get Hype Train Event endpoint.

hub.topic URL

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

Authentication

Required OAuth Scope: channel:read:hype_train

Required Query Parameters

Name Type Description
broadcaster_id string User ID of the broadcaster. Must match the User ID in the Bearer token.

Example hub.topic URL

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

Example Notification Payload

At 2020-04-24T20:07:24 user with id 134247454 contributed 200 bits towards the progression of the Hype Train on broadcaster with id 270954519:

{
  "data": [
    {
      "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
      "event_type": "hypetrain.progression",
      "event_timestamp": "2020-04-24T20:07:24Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "270954519",
        "cooldown_end_time": "2020-04-24T20:13:21.003802269Z",
        "expires_at": "2020-04-24T20:12:21.003802269Z",
        "goal": 1800,
        "id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
        "last_contribution": {
          "total": 200,
          "type": "BITS",
          "user": "134247454"
        },
        "level": 2,
        "started_at": "2020-04-24T20:05:47.30473127Z",
        "top_contributions": [
          {
            "total": 600,
            "type": "BITS",
            "user": "134247450"
          }
        ],
        "total": 600
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
  }
}