User - EventSub Reference | Twitch Developers

User Authorization Grant

The user.authorization.grant subscription type sends a notification when a user's authorization has been granted to your client id.

Note

This subscription type is only supported by Webhooks and Conduits, and cannot be used with WebSockets.

Subscription

Type: user.authorization.grant
Version: 1

Authorization

Requires one of the following:

An app access token.The Client ID in the token must match the client_id specified in the condition.

Subscription Request Body

typeStringRequired
The subscription type name: user.authorization.grant.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters. Pass in the client ID of the application you want to get user authorization grant notifications for.
Hide child attributesShow child attributes
- condition.client_idStringRequired
  Your application's client id. The provided client_id must match the client id in the application access token.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.client_idString
    Your application's client id. The provided client_id must match the client id in the application access token.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.client_idString
  The client_id of the application that was granted user access.
- event.user_idString
  The user id for the user who has granted authorization for your client id.
- event.user_loginString
  The user login for the user who has granted authorization for your client id.
- event.user_nameString
  The user display name for the user who has granted authorization for your client id.

Subscription Request Body Example

{
  "type": "user.authorization.grant",
  "version": "1",
  "condition": {
    "client_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "user.authorization.grant",
  "version": "1",
  "condition": {
    "client_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "user.authorization.grant",
        "version": "1",
        "status": "enabled",
        "cost": 1,
        "condition": {
            "client_id": "crq72vsaoijkc83xx42hz6i37"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "client_id": "crq72vsaoijkc83xx42hz6i37",
        "user_id": "1337",
        "user_login": "cool_user",
        "user_name": "Cool_User"
    }
}

User Authorization Revoke

The user.authorization.revoke subscription type sends a notification when a user's authorization has been revoked for your client id. Use this webhook to meet government requirements for handling user data, such as GDPR, LGPD, or CCPA.

Note

This subscription type is only supported by Webhooks and Conduits, and cannot be used with WebSockets.

Subscription

Type: user.authorization.revoke
Version: 1

Authorization

Requires one of the following:

An app access token.The Client ID in the token must match the client_id specified in the condition.

Subscription Request Body

typeStringRequired
The subscription type name: user.authorization.revoke.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters. Pass in the client ID of the application you want to get user authorization revoke notifications for.
Hide child attributesShow child attributes
- condition.client_idStringRequired
  Your application's client id. The provided client_id must match the client id in the application access token.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.client_idString
    Your application's client id. The provided client_id must match the client id in the application access token.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.client_idString
  The client_id of the application with revoked user access.
- event.user_idString
  The user id for the user who has revoked authorization for your client id.
- event.user_loginStringNullable
  The user login for the user who has revoked authorization for your client id. This is null if the user no longer exists.
- event.user_nameStringNullable
  The user display name for the user who has revoked authorization for your client id. This is null if the user no longer exists.

Subscription Request Body Example

{
  "type": "user.authorization.revoke",
  "version": "1",
  "condition": {
    "client_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "user.authorization.revoke",
  "version": "1",
  "condition": {
    "client_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "user.authorization.revoke",
        "version": "1",
        "status": "enabled",
        "cost": 1,
        "condition": {
            "client_id": "crq72vsaoijkc83xx42hz6i37"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "client_id": "crq72vsaoijkc83xx42hz6i37",
        "user_id": "1337",
        "user_login": "cool_user",
        "user_name": "Cool_User"   
    }
}

User Update

The user.update subscription type sends a notification when user updates their account.

Note

If you have the user:read:email scope for the user, the notification will include the email field.

Subscription

Type: user.update
Version: 1

Authorization

No authorization required.

Subscription Request Body

typeStringRequired
The subscription type name: user.update.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters. Pass in the user ID for the user you want update notifications for.
Hide child attributesShow child attributes
- condition.user_idStringRequired
  The user ID for the user you want update notifications for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.user_idString
    The user ID for the user you want update notifications for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.user_idString
  The user's user id.
- event.user_loginString
  The user's user login.
- event.user_nameString
  The user's user display name.
- event.emailString
  The user's email address. The event includes the user's email address only if the app used to request this event type includes the user:read:email scope for the user; otherwise, the field is set to an empty string. See Create EventSub Subscription.
- event.email_verifiedBoolean
  A Boolean value that determines whether Twitch has verified the user's email address. Is true if Twitch has verified the email address; otherwise, false.
  
  NOTE: Ignore this field if the email field contains an empty string.
- event.descriptionString
  The user's description.

Subscription Request Body Example

{
  "type": "user.update",
  "version": "1",
  "condition": {
    "user_id": "1337"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "user.update",
  "version": "1",
  "condition": {
    "user_id": "1337"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "user.update",
  "version": "1",
  "condition": {
    "user_id": "1337"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "user.update",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
           "user_id": "1337"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "event": {
        "user_id": "1337",
        "user_login": "cool_user",
        "user_name": "Cool_User",
        "email": "user@email.com",
        "email_verified": true,
        "description": "cool description"
    }
}

Whisper Received

The user.whisper.message subscription type sends a notification when a user receives a whisper.

Subscription

Type: user.whisper.message
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:whispers or user:manage:whispers scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:whispers or user:manage:whispers scope for the user represented by the user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: user.whisper.message.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.user_idStringRequired
  The user_id of the person receiving whispers.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.user_idString
    The user_id of the person receiving whispers.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.from_user_idString
  The ID of the user sending the message.
- event.from_user_nameString
  The name of the user sending the message.
- event.from_user_loginString
  The login of the user sending the message.
- event.to_user_idString
  The ID of the user receiving the message.
- event.to_user_nameString
  The name of the user receiving the message.
- event.to_user_loginString
  The login of the user receiving the message.
- event.whisper_idString
  The whisper ID.
- event.whisperObject
  Object containing whisper information.
  Hide child attributesShow child attributes
  - event.whisper.textString
    The body of the whisper message.

Subscription Request Body Example

{
  "type": "user.whisper.message",
  "version": "1",
  "condition": {
    "user_id": "423374343"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "user.whisper.message",
  "version": "1",
  "condition": {
    "user_id": "423374343"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "user.whisper.message",
  "version": "1",
  "condition": {
    "user_id": "423374343"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "7297f7eb-3bf5-461f-8ae6-7cd7781ebce3",
    "status": "enabled",
    "type": "user.whisper.message",
    "version": "1",
    "condition": {
      "user_id": "423374343"
    },
    "transport": {
      "method": "webhook",
      "callback": "https://example.com/webhooks/callback"
    },
    "created_at": "2024-02-23T21:12:33.771005262Z"
  },
  "event": {
    "from_user_id": "423374343",
    "from_user_login": "glowillig",
    "from_user_name": "glowillig",
    "to_user_id": "424596340",
    "to_user_login": "quotrok",
    "to_user_name": "quotrok",
    "whisper_id": "some-whisper-id",
    "whisper": {
      "text": "a secret"
    }
  }
}