Stream Webhook Update


#1

The /helix/streams API endpoint allows you to retrieve a stream’s online status, title, game, language, etc. However, the corresponding webhook only triggers when the online status changes.

As of today, this webhook will now trigger on any change to the stream. So whether the broadcaster went online, changed their title, or switched games, your webhook will notify you of the update!

Please let us know your feedback about this update in the comments below. Enjoy!


Getting Golive Event for Changing Game
#2

Just for clarification, is it any change to the stream object (so even including viewer_count, or stream id/started_at that might indicate a momentary outage, but not sufficient to trigger a stream down/up), or just those specific fields you mentioned?


#3

Really good question! Our objective is to trigger on every field in the /helix/streams API except viewer_count and thumbnail_url.


#4

Although it’s just semantics, note that the docs have changed to indicate the topic is " Stream Changed" rather than “Stream up/down” since it has a broader range of events now. There is no change to the URL of course.


#5

It’s a shame there’s no intention to include viewer_count, I know analytics is a niche use case compared to the majority of devs using that endpoint, but it would be nice to one day move away from so much polling and more to webhooks. It’s a great update regardless, I’m really liking what Twitch is doing with webhooks :slight_smile:


#6

Thanks @Dist!

Unfortunately viewer_count would be too noisy for our larger streams. We’ve considered models where we batch viewer_count changes together (e.g. send a webhook with an updated viewer_count every minute) but haven’t started down that path. Perhaps we’ll pursue a feature like that more seriously in the future.

However we definitely wanted to get this change out first :slightly_smiling_face:


#7

I am absolutely stoked about an update like this. Absolutely love webhooks vs polling.

Started doing some tests today though and things are looking a little wonky.

Went live, got the hook call as normal.

Updated the stream a handful of times over the course of 10 - 15 minutes, no calls.

Ended the stream, received the last of the hook calls for stream updating (updates game & title). Still no “end stream” (empty body) call within the last half hour for my test stream.


#8

Hey @TheElm, thanks for posting! Do you possibly have the notification ID for that last event? I can look it up in our system


#9

Here is my live notification

Notification-ID: 5d5bed9c-6145-5743-ad35-b9b318134735

{
  "data": [{
    "community_ids": [],
    "game_id": "458688",
    "id": "30627358304",
    "language": "",
    "started_at": "2018-10-04T02:11:43Z",
    "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_theelm-{width}x{height}.jpg",
    "title": "Bot webhook testing",
    "type": "live",
    "user_id": "19889057",
    "viewer_count": 0
  }]
}

and what is supposed to be the “offline” notification

Notification-ID: d8b2d5ca-9f2c-59bf-adc4-81e5e57ed1b3

{
  "data": [{
    "community_ids": [],
    "game_id": "458688",
    "id": "30627358304",
    "language": "en",
    "started_at": "2018-10-04T02:11:43Z",
    "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_theelm-{width}x{height}.jpg",
    "title": "Bot webhook testing",
    "type": "live",
    "user_id": "19889057",
    "viewer_count": 0
  }]
}

This is only from going live, and offline. Oddly both send the same information, aside from the “language”.

Thanks.


#10

Excellent, thanks! We believe to have a solution and will try to resolve quickly


#11

Any update on the offline notification looking the same as going live?

Other than this issue, updates on stream title change are working nicely. The decreased delay between stream going live and the webhook firing is appreciated too.


#12

We just deployed a change that we believe has corrected this error. We have additional improvements planned (in particular to latency) planned for next week


#13

Hi, new developer here with a few questions about this change.

I currently have a bot that sends a “just went live” notification of selected streams to a messaging app. So after the change now I have to figure out if it’s a online/offline notification, or a stream change.

So I imagine I do that by keeping a record of the “started_at” field and compare with subsequent events or by remembering the online status state.

Then I started wondering if title/game category changes will trigger the webhook while the stream is offline?
I’m assuming not, but if it does, what would be a good way to tell offline title changes and went online triggers apart? I guess I look at the type field? but the documentation is saying it’s only blank in case of an error which has a little worried.

Any suggestions will be appreciated
Thanks!

Oh! and just to make sure my understanding of the “started_at” field is correct as the API reference description doesn’t say much; but judging from the name, I assume it is when the stream started, and will remain the same until the current stream ends.


#14

When a stream is offline, the api returns an empty array, meaning that a broadcaster can change the title as much as they like but it makes no difference at all to the API as there’s no stream object to be changed, it’s still just an empty array. Because the underlying API for the webhook didn’t change, no notifications will be sent out if a topic change happens while offline.

Yes, the started_at field is when the stream went live. Under ideal conditions it’ll remain constant until the broadcaster ends their stream, but if there is a short connection drop it’s possible for it to be counted as a new stream when they’re back online and there’ll be a new started_at and id.


#15

Thanks a million Dist, answered all my questions.


#16

I’ve been seeing what I would consider “slow” incoming webhooks. Based on the docs and information I’ve read here, I sorta thought webhooks would be sent relatively quickly after the stream’s state changes. Maybe a few seconds to 10-15 seconds? However, I’m seeing upwards of 1.5 minutes before some webhooks arrive, if ever. For example, this evening I tried a few tests and have not yet received a “stream down” webhoo, even within 5-20 minutes after I shut down a stream.

What sort of expectations should I have on these webhooks being delivered?

An example of a notification ID that actually arrived: dff9660f-595c-59da-b970-327085009d0a

That arrived at least 130 seconds after I started the stream. I shut down the stream shortly after. I haven’t seen any webhooks posted since then to say that the stream is offline.


#17

Of course now, a few moments after I post this, the stop event arrives. :slight_smile: Still, it took awhile… and I’m pretty sure some of them have never arrived.


#18

Webhooks will always have some delay before sending notifications to ensure consistency between all cache servers of the underlying API endpoint. For some topics, such as stream change, there are additional delays on things like a stream going down so that if it’s just a momentary connection drop that is recovered from it wont send out a notification.

up to 3 minutes is common in most cases, with a stream doing down often taking around 5 minutes.

Twitch have said they’re working to reduce the delay, so expect some improvements in the future but no ETA on when.


#19

Our goal is for the webhook to fire as soon as the data is available via the API. While the majority of webhooks do this well, the “Stream Changed” webhook has been a challenge. We are currently taking steps to try and reduce the latency.

However, please keep in mind that there is still latency between stream ingestion and the API that is unavoidable for many of the reasons that @Dist mentioned :slight_smile: