Managing event subscriptions
Twitch provides a number of events that you can subscribe to to get near real time notifications. For a list of events, see EventSub Subscription Types.
But before you subscribe to events, you need write your event handler; otherwise, your subscription request will fail with webhook_callback_verification_failed. For information about writing your event handler, see Handling events.
Subscribing to events
Each subscription type includes the information you need to provide in your subscription request. All subscription types include the following information:
- The subscription type identifies the event. For example, to get notifications when a broadcaster gets a new follower, you’d set the
type
field to channel.follow. For information about handling subscription types that specify scopes, see (Authorization)[#authorization]. - The version number identifies which definition of the subscription request to use. For example, to use the first definition that Twitch defined for channel.follow, you’d set the
version
field to 1. - The condition identifies the parameters under which the event fires. For example, if you’re requesting notifications when a broadcaster gets a new follower, you’d set the
condition.broadcaster_user_id
field to the broadcaster’s ID. - The transport information tells Twitch which transport method you’re using for your callback (for example, webhook). This includes your event handler’s URI and the secret used to verify the event’s data. The URI must use SSL on port 443. For information about the secret, see Verifying the event message.
The following example shows how to create a subscription. For information about the /helix/eventsub/subscriptions
endpoint, see Create EventSub Subscription.
curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{"type":"channel.follow","version":"1","condition":{"broadcaster_user_id":"1234"},"transport":{"method":"webhook","callback":"https://example.com/callback","secret":"s3cre77890ab"}}'
The response contains a JSON object that echoes your request. The status
field indicates the state of your subscription. The status is set to webhook_callback_verification_pending while Twitch attempts to verify that you own the event handler specified in the callback
field; Twitch won’t send you events until it verifies the callback. After Twitch verifies your callback, the subscription’s status changes to enabled, which indicates that your subscription is active and able to receive events.
{
"data": [
{
"id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
"status": "webhook_callback_verification_pending",
"type": "channel.follow",
"version": "1",
"cost": 1,
"condition": {
"broadcaster_user_id": "12826"
},
"transport": {
"method": "webhook",
"callback": "https://example.com/webhooks/callback"
},
"created_at": "2019-11-16T10:11:12.123Z"
}
],
"total": 1,
"total_cost": 1,
"max_total_cost": 10000
}
Authorization
To create a subscription, you must use an app access token (the request fails if you use a user access token). For subscription types that require user authorization, the user must grant your app (client ID) permissions to the required scopes prior to subscribing to the event.
For example, to subscribe to channel.subscribe events, the broadcaster must grant your app permission to get users that subscribe to them, which adds the channel:read:subscriptions scope to your app’s client ID. If your client ID doesn’t include the scope, the subscription request fails. (This means that prior to sending a subscription request, your app must get a user access token, which adds the required scope to your client ID.)
Getting the list of events you subscribe to
To get the list of events that you subscribe to, send a GET request to the /helix/eventsub/subscriptions
endpoint. The list is paginated and is in ascending order by creation date (oldest subscription first).
The following request shows how to get the first page of events that you subscribe to. For details about this request, see Get EventSub Subscriptions.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
The response contains a JSON object for each event you subscribe to.
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "enabled",
"type": "streams.online",
"version": "1",
"cost": 1,
"condition": {
"broadcaster_user_id": "1234"
},
"created_at": "2020-11-10T20:08:33Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
}
},
{
"id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
"status": "webhook_callback_verification_pending",
"type": "users.update",
"version": "1",
"cost": 1,
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T20:31:52Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
}
}
],
"total": 2,
"total_cost": 2,
"max_total_cost": 10000,
"pagination": {}
}
Because it can take a few seconds for the total
field to update after subscriptions are added or deleted, you should consider the value an approximation.
For information about the cost
, total_cost
, and max_total_cost
fields, see Subscription limits.
Paging the results
If there is more than one page of results available, the Pagination object contains the cursor
field. To get the next page of results, set the request’s after query parameter to the cursor
field’s value.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions?after=abc123def456' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Filtering the list by type
You can filter the list of subscriptions by the event’s type and status. The filters are mutually exclusive (you cannot specify both type and status in the same request).
To filter the list by type, set the type query parameter to a subscription type. The following example filters the list for all channel.follow subscriptions.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions?type=channel.follow' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Filtering the list by status
To filter the list by the subscription’s status, set the status query parameter to one of the following values:
- enabled — Twitch has verified your callback and is able to send you notifications.
- webhook_callback_verification_pending — Twitch is verifying that you own the callback specified in the create subscription request. For information about how it does this, see Verifying your callback.
- webhook_callback_verification_failed — Twitch failed to verify that you own the callback specified in the create subscription request. Fix your event handler to correctly respond to the challenge, and then try subscribing again.
- notification_failures_exceeded — Twitch revoked your subscription because the notification delivery failure rate was too high.
- authorization_revoked — Twitch revoked your subscription because the users in the
condition
object revoked their authorization letting you get events on their behalf, or changed their password. - user_removed — Twitch revoked your subscription because the users in the
condition
object are no longer Twitch users.
The following example filters the list for all enabled subscriptions.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions?status=enabled' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Deleting a subscription
To delete a subscription, send a DELETE request to the /helix/eventsub/subscriptions
endpoint. Set the id query parameter to the subscription to delete. For details about this request, see Delete EventSub Subscription.
curl -X DELETE 'https://api.twitch.tv/helix/eventsub/subscriptions?id=f1c2a387-161a-49f9-a165-0f21d7a4e1c4' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Subscription Limits
EventSub uses a cost-based system for subscription limits. Subscription responses include the following fields to help you keep track of your subscription limits:
cost
— How much the subscription counts against your application’s limit.total_cost
— The current sum of all your subscription costs.max_total_cost
— Your application’s subscription limit.
The maximum number of subscriptions you can create grows as users authorize your application. Here’s how it works:
- There is a limit of 3 subscriptions with the same
type
andcondition
values. - There is no cost for subscriptions that require a user to authorize your application (e.g.,
channel.subscribe
). - There is a cost for subscriptions that require you to specify a user but does not require that user to authorize your application (e.g.,
channel.follow
,channel.update
). However, there is no cost if that user has authorized your application (i.e., you have an OAuth scope for that user).
Example
Suppose you want to create three subscriptions:
channel.follow
(no auth requirements, cost 1)channel.update
(no auth requirements, cost 1)channel.cheer
(bits:read
OAuth scope required, cost 0)
User A has granted bits:read
authorization to your application. Because the user has authorized your application, the total cost of these three subscriptions is 0.
User B has granted channel:moderate
authorization to your application. The cost of subscribing to channel.follow
and channel.update
subscriptions is 0. Your application cannot create a channel.cheer
subscription because User B has not authorized your application with the required OAuth scope.
User C has not granted authorization to your application. The cost of subscribing to channel.follow
and channel.update
subscriptions is 2. Your application cannot create a channel.cheer
subscription because User C has not authorized your application with the required OAuth scope.