Webhooks Guide

Starting on April 30, 2020, all Helix endpoints will require OAuth and matching client IDs. See this announcement for more details. Documentation will be updated as these requirements go into effect.

Introduction

Webhooks enable your application to subscribe to events that happen on Twitch. When an event to which you are subscribed occurs, Twitch notifies you. For example, you may want to know when:

• A user has a new follower.
• A stream has changed state.
• A whisper is sent (future).

Notifications are sent within seconds of event occurrence. Twitch takes extra steps to ensure your notifications are received, even if your servers are down.

Webhooks adhere to the W3C WebSub specification, a popular implementation that is successfully deployed throughout the industry. As stated in the spec:

WebSub provides a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP web hooks. Subscription requests are relayed through hubs, which validate and verify the request. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.

This guide covers the most pertinent aspects of WebSub; see the spec for details.

Webhooks are a way for you to receive new data as it comes into Twitch, without having to maintain a connection. When new data comes in, Twitch sends you an HTTP request with the event data. You can take advantage of this push model to load balance or proxy requests, just as you would do with production Web traffic.

Subscriptions

When you submit a request to subscribe to an event (with the [Subscribe To/Unsubscribe From Events](/api/webhooks-reference/#subscribe-tounsubscribe-from-events) endpoint), your request is asynchronously validated to confirm you are allowed to create the subscription. Depending on the results of this validation, Twitch responds by sending you one of two GET requests:

• Subscription verify — If your subscription request passes review, Twitch sends you a request to confirm that you requested the subscription. To confirm, respond to the request with the challenge token provided (hub.challenge) in the query parameters and an HTTP success (2xx) response code. Important Note The challenge token should be echoed back in a simple text/plain response, without any JSON/HTML wrapping.
• Subscription denied — In this case, the request payload explains why the subscription could not be created. For example, you may not be authorized to access the resource you requested or you may have exceeded the maximum number of subscriptions.

For examples, see the Webhooks reference documentation.

All subscriptions have an expiration time, which cannot exceed 10 days. To renew a subscription, make a new subscription request with the same parameters as the original request.

Limits: By default, each client ID can have at most 10,000 subscriptions. Also, you can subscribe to the same topic at most 3 times. 

Getting Notifications

When an event to which you are subscribed occurs, Twitch sends you a POST request with notification data. If you do not get the notification (e.g., your service is down), Twitch retries, with exponential backoff. Note that a failed notification does not revoke a subscription.

Rarely, the same notification may be delivered to you twice. For this reason, a unique ID is included in each notification payload. If you want your application to ignore duplicate notifications, keep track of these notification IDs and ensure you do not process the same notification twice.

On receiving a notification, your application should respond immediately with an HTTP success (2xx) response code, to acknowledge successful receipt of the notification. All other response codes are considered failures and will cause a number of retries. The response code should not be affected by whether your application successfully processed the notification.

Disambiguating Payloads

To easily disambiguate notification payloads from each other (especially for stream down events), you are recommended to use a different callback URL for each subscription; e.g. changing the path or the query parameters. This is also a way you can provide your own application-specific information to your callbacks.

Verifying Payloads

If a secret was provided when you created the subscription, Twitch signs the notification payload using that secret. We strongly recommend you verify the signature to confirm that the notification is genuine.

To verify payloads, you need to compute the hash properly. A common reason this may fail is unexpected string manipulation (e.g., JSON encoding or character escaping), which is done automatically by some web frameworks. To debug this, verify that the value of the content-length header matches the number of bytes you received in the notification payload. You may discover that notification hashing for payloads is failing due to unusual Unicode.