Webhooks Reference

As of April 30, 2020, all Helix endpoints require OAuth and matching client IDs. See this announcement for more details.

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

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

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

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

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

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.
`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"
  }
}

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

Example hub.topic URL

Example Notification Payload

Topic: Moderator Change Events

Hub Topic URL

Required Query Parameters

Optional Query Parameter

Example hub.topic URLs

Example Notification Payload

Topic: Channel Ban Change Events

Hub Topic URL

Required Query Parameters

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

Topic: Hype Train Event

hub.topic URL

Authentication

Required Query Parameters

Example hub.topic URL

Example Notification Payload