Drop - EventSub Reference | Twitch Developers

Drop Entitlement Grant

The drop.entitlement.grant subscription type sends a notification when an entitlement for a Drop is granted to a user.

Note

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

Subscription

Type: drop.entitlement.grant
Version: 1

Authorization

Requires one of the following:

An app access token.The Client ID associated with the access token must be owned by a user who is part of the specified organization.

Subscription Request Body

typeStringRequired
The subscription type name: drop.entitlement.grant.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters. Pass in the organization_id to subscribe to all drop entitlement grant notifications for that organization.
Hide child attributesShow child attributes
- condition.organization_idStringRequired
  The organization ID of the organization that owns the game on the developer portal.
- condition.category_idString
  The category (or game) ID of the game for which entitlement notifications will be received.
- condition.campaign_idString
  The campaign ID for a specific campaign for which entitlement notifications will be received.
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.
is_batching_enabledBooleanRequired
Needs to be true for this subscription type.

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.organization_idString
    The organization ID of the organization that owns the game on the developer portal.
  - subscription.condition.category_idString
    The category (or game) ID of the game for which entitlement notifications will be received.
  - subscription.condition.campaign_idString
    The campaign ID for a specific campaign for which entitlement notifications will be received.
- 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.
eventsObject[]
The entitlements granted in this notification. This type batches, so a notification carries one or more.
Hide child attributesShow child attributes
- events.idString
  Individual event ID, as assigned by EventSub. Use this for de-duplicating messages.
- events.dataObject
  The granted entitlement.
  Hide child attributesShow child attributes
  - events.data.organization_idString
    The ID of the organization that owns the game that has Drops enabled.
  - events.data.category_idString
    Twitch category ID of the game that was being played when this benefit was entitled.
  - events.data.category_nameString
    The category name.
  - events.data.campaign_idString
    The campaign this entitlement is associated with.
  - events.data.user_idString
    Twitch user ID of the user who was granted the entitlement.
  - events.data.user_nameString
    The user display name of the user who was granted the entitlement.
  - events.data.user_loginString
    The user login of the user who was granted the entitlement.
  - events.data.entitlement_idString
    Unique identifier of the entitlement. Use this to de-duplicate entitlements.
  - events.data.benefit_idString
    Identifier of the Benefit.
  - events.data.created_atString
    UTC timestamp in ISO format when this entitlement was granted on Twitch.

Subscription Request Body Example

{
  "type": "drop.entitlement.grant",
  "version": "1",
  "condition": {
    "organization_id": "9001",
    "category_id": "9002",
    "campaign_id": "9003"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  },
  "is_batching_enabled": true
}

{
  "type": "drop.entitlement.grant",
  "version": "1",
  "condition": {
    "organization_id": "9001",
    "category_id": "9002",
    "campaign_id": "9003"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  },
  "is_batching_enabled": true
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "drop.entitlement.grant",
        "version": "1",
        "status": "enabled",
        "condition": {
           "organization_id": "9001",
            "category_id": "9002",
            "campaign_id": "9003" 
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2019-11-16T10:11:12.634234626Z"
    },
    "events": [
        {
            "id": "bf7c8577-e3e3-4881-a78a-e9446641d45d",
            "data": {
                "organization_id": "9001",
                "category_id": "9002",
                "category_name": "Fortnite",
                "campaign_id": "9003",
                "user_id": "1234",
                "user_name": "Cool_User",
                "user_login": "cool_user",
                "entitlement_id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
                "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
                "created_at": "2019-01-28T04:17:53.325Z"
            }
        },
        {
            "id": "bf7c8577-e3e3-4881-a78a-e9446641d45c",
            "data": {
                "organization_id": "9001",
                "category_id": "9002",
                "category_name": "Fortnite",
                "campaign_id": "9003",
                "user_id": "12345",
                "user_name": "Cooler_User",
                "user_login": "cooler_user",
                "entitlement_id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
                "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
                "created_at": "2019-01-28T04:17:53.325Z"
            }
        }
    ]
}