Webhooks Reference

WebSub-based webhooks are deprecated and are scheduled to be decommissioned on or soon after September 16, 2021. If you are getting started with webhooks or need to migrate, see EventSub. For more information about this deprecation, see our announcement on the forums.

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

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.  

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

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": "3d141868-46ed-4ef8-cd09-1fbb4f845355",
      "user_id": "56145452",
      "user_login": "testBroadcaster",
      "user_name": "testBroadcaster",
      "game_id": "509658",
      "game_name": "Just Chatting",
      "type": "live",
      "title": "Example title from the CLI!",
      "viewer_count": 9848,
      "started_at": "2021-03-20T03:18:50Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_twitch_user-{width}x{height}.jpg",
      "tag_ids": []
    }
  ]
}

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

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

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

Optional Query Parameter

Example hub.topic URLs

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

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

Required Query Parameters

Optional Query Parameter

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": "b0809075-c618-ee8e-705b-b1d5dcbdf9ee",
      "event_type": "moderation.user.ban",
      "event_timestamp": "2021-03-20T03:22:49Z",
      "version": "v1",
      "event_data": {
        "broadcaster_id": "10019343",
        "broadcaster_login": "testBroadcaster",
        "broadcaster_name": "testBroadcaster",
        "user_id": "34304448",
        "user_login": "testFromUser",
        "user_name": "testFromUser",
        "expires_at": "2021-03-20T04:22:49Z"
      }
    }
  ]
}

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. 

Warning: The data returned from this topic may be unreliable. If you need notifications for new channel subscriptions, consider using EventSub’s channel.subscribe subscription type for channel subscribe events. Learn more about EventSub.

Hub Topic URL

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

Authentication

Required OAuth Scope: channel:read:subscriptions

Required Query Parameters

Optional Query Parameters

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

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": "2021-03-20T03:26:24Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "270954519",
        "cooldown_end_time": "2021-03-20T03:26:24Z",
        "expires_at": "2021-03-20T03:26:24Z",
        "goal": 1800,
        "id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
        "last_contribution": {
          "total": 200,
          "type": "subscription",
          "user": "134247454"
        },
        "level": 2,
        "started_at": "2021-03-20T03:26:24Z",
        "top_contributions": [
          {
            "total": 600,
            "type": "bits",
            "user": "134247450"
          }
        ],
        "total": 600
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
  }
}