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