Webhooks

Webhooks let you hook into events that happen throughout the Wistia platform.

Webhooks let you know about events that happen in Wistia as they occur. Want to send an alert as soon as a prospect fills out a Turnstile? 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:

HeaderDescription
HostThe URL of your consumer, which you provide when configuring a webhook.
User-AgentWistia-Webhooks/{VERSION}. The current version is 0.0.47.
X-Wistia-SignatureAn 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-TypeThe output format will always be JSON, so this will always be application/json.
Content-LengthThe byte length of the request body.

Example Signature Generation

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:

FieldDescription
uuidA universally-unique ID for this instance of the event. You should only pay attention to the first instance.
typeThe type of event, like media.updated
generated_atWhen the event occurred in Wistia. This is always in ISO-8601 format, and always in UTC.
payloadThese 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

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

FieldDescription
mediaThe media object
previous_attributesThe attribute(s) that got updated, and what they were previously

Example delivery

{
  "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

FieldDescription
mediaThe media object that was deleted

Example delivery

{
  "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

FieldDescription
visitorThe visitor object, containing the visitor's ID
viewing_sessionObject containing the ID of the viewing_session.
mediaThe 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

{
  "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

FieldDescription
visitorThe visitor who watched the video
viewing_sessionThe viewing_session object
percent_watchedThe percent_watched threshold reached
mediaThe media object

Example delivery

{
  "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

FieldDescription
visitorThe visitor object for the visitor who submitted their information to Turnstile
viewing_sessionThe viewing_session object
nameThe name of the visitor, if provided
mediaThe media object for the media the Turnstile is on
emailThe email address of the visitor

Example delivery

{
  "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

FieldDescription
visitorThe visitor object for the visitor who clicked the CTA
viewing_sessionThe viewing_session object
urlThe URL that the CTA points to
mediaThe media object for the media the CTA is on

Example delivery

{
  "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"
  }]
}

Payload structure

FieldDescription
visitorThe visitor who clicked the Annotation link
viewing_sessionThe viewing_session in which the visitor clicked the Annotation Link
urlThe URL the Annotation Link points to
mediaThe media object for the media the Annotation Link is on

Example delivery

{
  "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.

Choosing a trigger app with 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.

Webhooks events options

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.

Webhooks Zapier events payload

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.

Slack Webhook example with Zapier

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