Wistia

to the tippy ↑

Webhooks

Warning: You are heading into developer territory!

Our APIs are designed for programmers. If our APIs were a ski trail, they'd be a nice blue cruiser - anyone can do it, but expect to fall a few times if you don't know what you're doing!

If you're new to web development, we recommend taking a lesson before you hit our slopes. Try a class from Frontend Masters or Skillshare!

Webhooks let you know about events that happen in Wistia as they occur. Want to send an alert as soon as a new video is processed and ready to play? Perhaps get new stats pushed from Wistia into your custom dashboard as people watch your videos? Well then, you and webhooks will be fast friends.

Want to use webhooks, but hate the technical aspect of setting them up? Good news! Check out our Zapier section for all of the details.

Alert

Webhoooks are now available to turn on in the Beta Features Section of your Account Settings!

Overview

When you have a webhook configured for a particular event in Wistia, we'll send a HTTP POST request to the URL of your choice anytime that event occurs, containing the data you'll want about what happened. That's it!

To configure a new webhook, head to the Webhooks section of your Account Settings. Or, read on for more information about the available event types and the structure of the data.

Glitch

Remix this app to try webhooks instantly: Wistia Webhooks Example.

Request Format

Headers

The POST request to your webhooks consumer will contain the following headers:

Header Description
Host The URL of your consumer, which you provide when configuring a webhook.
User-Agent Wistia-Webhooks/{VERSION}. The current version is 0.0.47.
X-Wistia-Signature An HMAC hexdigest of the POST body, computed using the secret_key provided when configuring the webhook. You should be using a sha256 HMAC hexdigests.
Content-Type The output format will always be JSON, so this will always be application/json.
Content-Length The byte length of the request body.

Example Signature Generation

signature.rb
1
2
3
payload_body = request.body.read
secret_key = SECRET_KEY_AS_DEFINED_IN_WISTIA
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret_key, payload_body)

Request Body

Within the body of the request, there will always be two things: a hook (containing a uuid for that webhook message), and an array of events. Note that even if there's only a single event, it will always be contained in an events array. Within that array, each event will have the following fields:

Field Description
uuid A universally-unique ID for this instance of the event. You should only pay attention to the first instance.
type The type of event, like media.updated
generated_at When the event occurred in Wistia. This is always in ISO-8601 format, and always in UTC.
payload These are the data you're looking for.

The Payload

The payload for each event contains the data about what happened, and the object that it happened to. The structure for each event type is may vary to include relevant information. Check out the events list for details on each one.

Example POST

wistia_js.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
POST /to HTTP/1.1

Host: where.im.going
User-Agent: Wistia-Webhooks/{VERSION}
X-Wistia-Signature: 23948kwer9ewrkj2340981aszxcmnvie
Content-Type: application/json
Content-Length: ...

{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e67f16e673a000",
    "type": "media.updated",
    "payload": {
      "media": {
        "url": "http://dave.wistia.com/medias/f5diqltruh",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/21d23d756f30711e7a5e66815d7d74900515ba29.jpg?image_crop_resized=200x120"
        },
        "name": "Cakes on cakes on cakes",
        "id": "f5diqltruh",
        "duration": 7.676
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:53:15Z"
  }]
}

Events

Tip

Webhooks are currently available for the following events in Wistia. We plan on adding more, so please let us know if you don't see the event you want listed here. Also let us know if you do see the event you want, but it doesn't provide the data you need.

media.updated

A media is updated when its title, description, or thumbnail image changes. These can all be changed through the UI on the media's page in your Wistia account, or through the Data API.

Payload structure

Field Description
media The media object
previous_attributes The attribute(s) that got updated, and what they were previously

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e6729eecb3a000",
    "type": "media.updated",
    "payload": {
      "media": {
        "url": "http://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/aa2863d2bf45cf2cc5c325d129e80bd5c0055883.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      },
      "previous_attributes": {
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        }
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:10:13Z"
  }]
}

media.deleted

Payload structure

Field Description
media The media object that was deleted

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e67f16f873a000",
    "type": "media.deleted",
    "payload": {
      "media": {
        "id": "f5diqltruh"
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:57:05Z"
  }]
}

viewing_session.play

The viewing_session.play event occurs when a person presses play on a video for the first time per visit to a page, or the video autoplays.

Payload structure

Field Description
visitor The visitor object, containing the visitor's ID
viewing_session Object containing the ID of the viewing_session.
media The media object

Note

In the Stats API, what's referred to as the viewing_session here is currently just called an event. viewing_session will be the name in v2 of our API 🔮.

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e7b27100b3a000",
    "type": "viewing_session.play",
    "payload": {
      "visitor": {
        "id": "v20150227_c651bc81-8ec8-445b-b8a0-878d19278d35"
      },
      "viewing_session": {
        "id": "v20150225_e17a7db7-da7d-4d56-b5a8-ce6a9b62a800"
      },
      "media": {
        "url": "http://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-31T13:59:22Z"
  }]
}

viewing_session.percent_watched

As a person watches a video, the percent_watched increases. This event will get triggered when the percent_watched reaches each of four major thresholds: 25%, 50%, 75%, and 100%.

Payload structure

Field Description
visitor The visitor who watched the video
viewing_session The viewing_session object
percent_watched The percent_watched threshold reached
media The media object

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e67473ecb3a000",
    "type": "viewing_session.percent_watched",
    "payload": {
      "visitor": {
        "id": "v20150227_bee7121c-04bb-42ae-abc9-5327f536df0f"
      },
      "viewing_session": {
        "id": "v20150225_52967e29-8196-42d8-9dc6-952c1d9ec87f"
      },
      "percent_watched": 25,
      "media": {
        "url": "http://dave.wistia.com/medias/mmgzi8h6yh",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/23c4846eecd462beab57a508dff7f052a5faf065.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "mmgzi8h6yh",
        "duration": 71.912
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:14:01Z"
  }]
}

viewing_session.turnstile.converted

A visitor was tagged with an email address, and potentially their first and last name, by entering their information into Turnstile.

Payload structure

Field Description
visitor The visitor object for the visitor who submitted their information to Turnstile
viewing_session The viewing_session object
name The name of the visitor, if provided
media The media object for the media the Turnstile is on
email The email address of the visitor

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e7b61ae133a000",
    "type": "viewing_session.turnstile.converted",
    "payload": {
      "visitor": {
        "id": "v20150227_e38e365e-77e2-41e2-b521-0723fca11b06"
      },
      "viewing_session": {
        "id": "v20150225_85d3bf5d-a60b-42fe-a5e6-b0e0eb1645f3"
      },
      "name": "Lenny Lavigne",
      "media": {
        "url": "http://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      },
      "email": "lenny@wistia.com"
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-31T14:03:04Z"
  }]
}

viewing_session.call_to_action.converted

If your video has a Call To Action, this event will fire when the visitor clicks on it.

Payload structure

Field Description
visitor The visitor object for the visitor who clicked the CTA
viewing_session The viewing_session object
url The URL that the CTA points to
media The media object for the media the CTA is on

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e67b56f1b3a000",
    "type": "viewing_session.call_to_action.converted",
    "payload": {
      "visitor": {
        "id": "v20150227_199a749f-db0c-4d0b-84b1-cabe496be192"
      },
      "viewing_session": {
        "id": "v20150225_3783d72c-3834-4d0f-bc7b-c624c437e3a6"
      },
      "url": "https://wistia.com",
      "media": {
        "url": "http://dave.wistia.com/medias/9xa4r4b4z0",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/d01f7a9a38dd3e9308098e8fce11b2b09567935d.jpg?image_crop_resized=200x120"
        },
        "name": "Cakes on cakes on cakes",
        "id": "9xa4r4b4z0",
        "duration": 7.676
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:26:01Z"
  }]
}

viewing_session.annotation_link.converted

Payload structure

Field Description
visitor The visitor who clicked the Annotation link
viewing_session The viewing_session in which the visitor clicked the Annotation Link
url The URL the Annotation Link points to
media The media object for the media the Annotation Link is on

Example delivery

wistia_delivery.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e679f29c73a000",
    "type": "viewing_session.annotation.converted",
    "payload": {
      "visitor": {
        "id": "v20150227_199a749f-db0c-4d0b-84b1-cabe496be192"
      },
      "viewing_session": {
        "id": "v20150225_3783d72c-3834-4d0f-bc7b-c624c437e3a6"
      },
      "url": "https://wistia.com",
      "media": {
        "url": "http://dave.wistia.com/medias/9xa4r4b4z0",
        "thumbnail": {
          "url": "http://embed.wistia.com/deliveries/d01f7a9a38dd3e9308098e8fce11b2b09567935d.jpg?image_crop_resized=200x120"
        },
        "name": "Cakes on cakes on cakes",
        "id": "9xa4r4b4z0",
        "duration": 7.676
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2016-03-30T15:23:45Z"
  }]
}

Ordering, Batching, and Uniqueness

We aim to ensure that every webhooks message is sent by Wistia and received by your consumer at least once. Since the order in which your consumer receives the messages cannot be guaranteed, and Wistia might send the same message multiple times in rare cases (say, the wait for a 200 OK response from your consumer exceeds the 10 second request timeout limit), each event in a message's body will specify a uuid and a generated_at timestamp. Your consumer should use this data to determine the proper order and uniqueness of events. If multiple received events have the same uuid, they're the same exact event, and it's safe to ignore all but one of them.

If multiple events occur within a very short timeframe, we'll batch them together into a single POST to avoid making an unreasonable amount of requests to your consumer. In such cases, the events array in the request body will contain multiple events.

Connecting to Zapier Example

One of the easiest ways to use Wistia's webhooks is to set up a zap with Zapier. You can begin by setting up your own Zapier account and selecting make a zap! at the top of the screen. You'll see an option to Choose a Trigger App. Within that option, select Webhooks.

On the next screen, select the Catch Hook option. Zapier will generate a catch URL that you'll need to copy into your Wistia account. In the Webhooks section of your Account Settings paste the catch URL in the box labeled POST URL. You will also need to enter a Secret Key (it can be whatever you want).

Next up, select the events you're interested in sending to your zap. Check the events section above for the full breakdown.

Hit that Submit button, and head back to Zapier.

The next option will be to Pick off a Child Key. For this step, you'll want to add events.payload into the text box.

After that, you'll get an option to test your webhook. There'll also be another opportunity to copy the catch URL from Zapier to your Wistia Account if you didn't already do this. Since you've already done this, click Okay, I did this and let's test things.

To trigger the webhook you'll want to watch one of your videos in an incognito, or private browsing, window. That should prompt a Test Successful message, indicating that Zapier is successfully receiving the webhook. Woohoo! 🎯

Now that the webhook is working you'll have the opportunity to set up the action Zapier takes upon receiving the webhook from Wistia.

You can set it up with various apps, and in the edit template section you'll be able to choose the various information from the webhook you'd like it to display. In the example below, the zap will post the video's name to Slack any time someone plays it.

After that, you'll be all set to receive your own custom webhooks!