Contents

Testing webhook events

The event command lets you trigger mock events for local webhook testing. If you use Create EventSub Subscription to subscribe to event notifications, use this feature to test your event handler.

To use this command, you must have implemented an EventSub event handler to process the event message. For details, see Handling event notifications.

Triggering webhook events

Use the trigger sub-command to send mock events. The command’s argument identifies the event to trigger. For example, the following command triggers a Subscribe event.

twitch event trigger subscribe -F https://localhost:8080/eventsub/ 

List of events you can trigger

The following is the list of events that you can trigger. Specify these as arguments of the trigger sub-command.

Argument Description
add-moderator Triggers a channel moderator add event.
add-redemption Triggers a channel points redemption event.
add-reward Triggers a channel points custom reward add event.
ban Triggers a channel ban event.
channel-gift Triggers a channel gifting event, which describes the number of gifts given by a user.
cheer Triggers a cheer event. Only usable with the eventsub transport.
drop Triggers a Drops entitlement event.
gift Triggers a gifted subscription event for a basic tier 1 sub.
grant Triggers an authorization grant event.
hype-train-begin Triggers a channel hype train start event.
hype-train-end Triggers a channel hype train end event.
hype-train-progress Triggers a channel hype train progress event.
poll-begin Triggers a channel poll begin event.
poll-end Triggers a channel poll end event.
poll-progress Triggers a channel poll progress event.
prediction-begin Triggers a channel prediction begin event.
prediction-end Triggers a channel prediction end event.
prediction-lock Triggers a channel prediction lock event.
prediction-progress Triggers a channel prediction progress event.
raid Triggers a channel raid event with a random viewer count.
remove-moderator Triggers a channel moderator remove event.
remove-reward Triggers a channel points custom reward remove event.
revoke Triggers a user authorization revoke event. Uses the local client specified in twitch configure or generates one randomly.
stream-change Triggers a stream changed event.
streamdown Triggers a stream offline event.
streamup Triggers a stream online event.
subscribe-message Triggers a subscription message event.
subscribe Triggers a standard subscription event for a basic tier 1 sub.
transaction Triggers a Bits in Extensions transactions events.
unban Triggers a channel unban event.
unsubscribe Triggers a standard unsubscribe event for a basic tier 1 sub.
update-redemption Trigger a channel points redemption update event.
update-reward Triggers a channel points custom reward update event.

Flags to use when triggering events

Use these flags to describe the event’s behavior or to specify its data.

Flag Shorthand Description Example
--forward-address -F The web server address to send the mock events to. -F https://localhost:8080
--transport -T The method used to send events. Default is eventsub. -T eventsub
--to-user -t The receiver’s user ID. Typically, this is the broadcaster’s user ID. -t 44635596
--from-user -f The sender’s user ID. For example, the ID of the user that follows another user, or the user that subscribes to a broadcaster. -f 44635596
--gift-user -g The user ID of the user that gifted the subscription. Used only for subscription-based events. -g 44635596
--secret -s The webhook secret used to sign the HMAC (this is the same secret that you specified in the subscription request). The secret is an ASCII string that’s between 10 and 100 characters long, inclusive. -s testsecret
--count -c The number of events to trigger. Used to simulate an influx of events. -c 100
--anonymous -a Indicates that the event is anonymous. Only applies to gift and cheer events. -a
--status -S The status of the event object. Only applies to channel points redemptions. -S fulfilled
--item-id -i The ID to use for the event payload item (for example, the reward ID in redemption events or the game ID in stream events). -i 032e4a6c-4aef-11eb-a9f5-1f703d1f0b92
--item-name -n The name to use for the event payload item (for example, the reward ID in redemption events or the game name in stream events). -n "Science & Technology"
--cost -C The amount of bits or channel points redeemed/used in the event. -C 250
--description -d The title to update or start the stream with. -d Awesome new title!
--game-id -G The game ID to use for Drop or other relevant events. -G 1234

Examples

The following examples show how to use the flags.

// Triggers a Subscribe event and forwards it to the localhost:8080 server.

twitch event trigger subscribe -F https://localhost:8080/eventsub/ 

// Triggers a cheer event from user 1234 to user 4567.

twitch event trigger cheer -f 1234 -t 4567 -F https://localhost:8080/eventsub/

Retrigger an event

The retrigger sub-command lets you resend previous events using the event’s ID. For example, if the previous event was:

{
  "subscription": {
    "id": "713f3254-0178-9757-7439-d779400c0999",
    "type": "channels.cheer",
    ...
  }
}

You’d retrigger the event using:

twitch event retrigger -i "713f3254-0178-9757-7439-d779400c0999" -F https://localhost:8080/eventsub/ 

Flags to use when retriggering events

Use these flags to identify the event and describe the event’s behavior.

Flag Shorthand Description Example
--forward-address -F The web server address to send mock events to. -F https://localhost:8080
--id -i Required. The ID of the event to trigger. -i <id>
--secret -s The webhook secret used to sign the HMAC (this is the same secret that you specified in the subscription request). The secret is an ASCII string that’s between 10 and 100 characters long, inclusive. -s testsecret

Verifying your event handler’s challenge response

The verify-subscription sub-command lets you test your event handler’s challenge response. When you subscribe to an event, Twitch verifies that you own the event handler specified in the request by sending your handler a webhook_callback_verification notification event. For more information, see Responding to a challenge request.

The following example verifies whether your event handler responds correctly to a challenge event.

twitch event verify-subscription cheer -F https://localhost:8080/eventsub/ 

The command’s output indicates whether response and status code are valid. The following shows a valid response.

✔ Valid response. Received challenge 5e784545-5a59-a05a-6ae6-cfaf260532f1 in body
✔ Valid status code. Received status 200

And this is what the output looks like if the response is malformed.

✗ Invalid response. Received  as body, expected b320aef5-dc43-5c42-e93e-9be75882a38c
✔ Valid status code. Received status 204

List of events you can subscribe to

The following is the list of events that you can subscribe to. Specify these as arguments of the verify-subscription sub-command.

Argument Description
add-moderator Triggers a channel moderator add event.
add-redemption Triggers a channel points redemption event.
add-reward Triggers a channel points custom reward add event.
ban Triggers a channel ban event.
channel-gift Triggers a channel gifting event, which describes the number of gifts given by a user.
cheer Triggers a cheer event. Only usable with the eventsub transport.
drop Triggers a Drops entitlement event.
gift Triggers a gifted subscription event for a basic tier 1 sub.
grant Triggers an authorization grant event.
hype-train-begin Triggers a channel hype train start event.
hype-train-end Triggers a channel hype train end event.
hype-train-progress Triggers a channel hype train progress event.
poll-begin Triggers a channel poll begin event.
poll-end Triggers a channel poll end event.
poll-progress Triggers a channel poll progress event.
prediction-begin Triggers a channel prediction begin event.
prediction-end Triggers a channel prediction end event.
prediction-lock Triggers a channel prediction lock event.
prediction-progress Triggers a channel prediction progress event.
raid Triggers a channel raid event with a random viewer count.
remove-moderator Triggers a channel moderator remove event.
remove-reward Triggers a channel points custom reward remove event.
revoke Triggers a user authorization revoke event. Uses the local client specified in twitch configure or generates one randomly.
stream-change Triggers a stream changed event.
streamdown Triggers a stream offline event.
streamup Triggers a stream online event.
subscribe-message Triggers a subscription message event.
subscribe Triggers a standard subscription event for a basic tier 1 sub.
transaction Triggers a Bits in Extensions transactions events.
unban Triggers a channel unban event.
unsubscribe Triggers a standard unsubscribe event for a basic tier 1 sub.
update-redemption Trigger a channel points redemption update event.
update-reward Triggers a channel points custom reward update event.

Flags to use when verifying your web server

Flag Shorthand Description Example
--forward-address -F Required. Your event handler’s web server address. -F https://localhost:8080/eventsub
--secret -s The webhook secret used to sign the HMAC (this is the same secret that you specified in the subscription request). The secret is an ASCII string that’s between 10 and 100 characters long, inclusive. -s testsecret
--transport -T The method used to send events. The default is eventsub. -T eventsub