Contents

Helix Endpoints

Create EventSub Subscription

Creates an EventSub subscription.

Authentication

URL

POST https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

None

Required Body Parameters

Name Type Description
type string The category of the subscription that is being created. Valid subscription types can be found here.
version string The version of the subscription type that is being created. Each subscription type has independent versioning. 
condition  condition  JSON object containing custom parameters for a particular subscription. 
transport  transport  JSON object containing notification delivery specific configuration including a method string. Valid transport methods include: webhook. In addition to the method string, a webhook transport must include the callback and secret information.

Optional Query Parameters

None

Example Request

curl -X POST \
  https://api.twitch.tv/helix/eventsub/subscriptions \
  -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
  -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
  -H 'Content-Type: application/json' \
  -d '{"type":"users.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}'

Response Fields

Field Type Description
data array Array containing 1 element: the created subscription.
id string ID of the subscription created.
status string Status of the subscription. Valid values are:enabled: designates that the subscription is in an operable state and is valid.

webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string The category of the subscription that was created.
version string The version of the subscription type that was created.
condition  condition  JSON object specifying custom parameters for the subscription.
created_at string RFC3339 timestamp indicating when the subscription was created.
transport  transport  JSON object indicating the notification delivery specific information. Includes the transport method and callback URL.
limit integer Subscription limit for client id that made the subscription creation request.
total integer Total number of subscriptions for the client ID that made the subscription creation request.

Example Response

{
    "data": [
        {
            "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
            "status": "webhook_callback_verification_pending",
            "type": "users.update",
            "version": "1",
            "condition": {
                "user_id": "1234"
            },
            "created_at": "2020-11-10T20:29:44Z",
            "transport": {
                "method": "webhook",
                "callback": "https://this-is-a-callback.com"
            }
        }
    ],
    "limit": 10000,
    "total": 1
}

Delete EventSub Subscription

Delete an EventSub subscription. 

Authentication

URL

DELETE https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

Name Type Description
id string The subscription ID for the subscription you want to delete.

Optional Query Parameters

None

Example Request

 curl -X DELETE \
  'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \
  -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
  -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2'

Response Fields

None

Example Response

204 No Content

Get EventSub Subscriptions

Get a list of your EventSub subscriptions.

Authentication

URL

GET https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

None

Optional Query Parameters

Use parameters to filter by subscription status or type. Only include one filter query parameter; if you specify both status and type parameters, you will receive an error response.

Name Type Description
status string Include this parameter to filter subscriptions by one status type. Valid values:

enabled: the subscription is in an operable state and is valid.

webhook_callback_verification_pending: subscription is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: subscription failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string Include this parameter to filter subscriptions by subscription type name (e.g., channel.update).

Example Request

curl -X GET \
  https://api.twitch.tv/helix/eventsub/subscriptions \
  -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
  -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2'

Response Fields

Field Type Description
data array Array containing subscriptions.
id string ID of the subscription.
status string Status of the subscription. Valid values are:enabled: designates that the subscription is in an operable state and is valid.

webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string The category of the subscription.
version string The version of the subscription.
condition  condition  JSON object specifying custom parameters for the subscription.
created_at string RFC3339 timestamp indicating when the subscription was created.
transport  transport  JSON object indicating the notification delivery specific information. Includes the transport method and callback URL.
limit integer Subscription limit for client id that made the subscription creation request.
total integer Total number of subscriptions for the client ID that made the subscription creation request.
pagination object A cursor value to be used in a subsequent request to specify the starting point of the next set of results.

Example Response

{
    "total": 2,
    "data": [
        {
            "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
            "status": "enabled",
            "type": "streams.online",
            "version": "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",
            "condition": {
                "user_id": "1234"
            },
            "created_at": "2020-11-10T20:31:52Z",
            "transport": {
                "method": "webhook",
                "callback": "https://this-is-a-callback.com"
            }
        }
    ],
    "limit": 10000,
    "pagination": {}
}