Helix Endpoints

Create EventSub Subscription

Creates an EventSub subscription.

Authentication

App access token required

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

App access token required

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

App access token required

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": {}
}