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:

1. 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].
2. 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.
3. 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.
4. 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 and condition 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:

1. channel.follow (no auth requirements, cost 1)
2. channel.update (no auth requirements, cost 1)
3. 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.