Wistia Learning Center
Guides
Login

Webhooks

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

Suggest Edits

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.

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.

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": "https://dave.wistia.com/medias/f5diqltruh",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/21d23d756f30711e7a5e66815d7d74900515ba29.jpg?image_crop_resized=200x120"
        },
        "name": "Cakes on cakes on cakes",
        "id": "f5diqltruh",
        "duration": 7.676
      },
      "project": {
        "id": "some-hashed-id",
        "name": "Folder Name",
      },
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-03-30T15:53:15Z"
  }]
}

📘

Note

The "duration" value is displayed in seconds.

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.

List of Events

media.created

The media.created event occurs when a media is created.

Payload structure

FieldDescription
mediaThe media object

Example delivery

{
  "hook": {
    "uuid": "a4ab9eb6-ab82-4dae-86f2-29f744f7d031"
  },
  "events": [
    {
      "uuid": "fc53f8f78b67d04d455029813f8ec1ef",
      "type": "media.created",
      "payload": {
        "media": {
          "duration": 40.207,
          "id": "vpe2p82q64",
          "name": "Lenny Delivers Video!",
          "thumbnail": {
            "url": "https://embed-ssl.wistia.com/deliveries/e96ea382701bc172657d90bf269211beddbf6f7f.jpg?image_crop_resized=200x120"
          },
          "url": "https://harper.wistia.com/medias/vpe2p82q64"
        },
        "project": {
       	 "id": "some-hashed-id",
       	 "name": "Folder Name",
      	},
      },
      "metadata": {
        "account_id": "0sxav1wj8o"
      },
      "generated_at": "2024-03-31T21:56:45Z"
    }
  ]
}

media.processing

The media.processing event occurs when processing is started.

Payload structure

FieldDescription
mediaThe media object

Example delivery

{
  "hook": {
    "uuid": "a4ab9eb6-ab82-4dae-86f2-29f744f7d031"
  },
  "events": [
    {
      "uuid": "fc53f8f78b67d04d455029813f8ec1ef",
      "type": "media.processing",
      "payload": {
        "media": {
          "duration": 40.207,
          "id": "vpe2p82q64",
          "name": "Lenny Delivers Video!",
          "thumbnail": {
            "url": "https://embed-ssl.wistia.com/deliveries/e96ea382701bc172657d90bf269211beddbf6f7f.jpg?image_crop_resized=200x120"
          },
          "url": "https://harper.wistia.com/medias/vpe2p82q64"
        },
        "project": {
          "id": "some-hashed-id",
          "name": "Folder Name",
        },
      },
      "metadata": {
        "account_id": "0sxav1wj8o"
      },
      "generated_at": "2024-03-31T21:56:45Z"
    }
  ]
}

media.ready

The media.ready event occurs when processing is complete and all dependent video and image assets have been successfully encoded. The media is ready for playback.

Payload structure

FieldDescription
mediaThe media object

Example delivery

{
  "hook": {
    "uuid": "a4ab9eb6-ab82-4dae-86f2-29f744f7d031"
  },
  "events": [
    {
      "uuid": "fc53f8f78b67d04d455029813f8ec1ef",
      "type": "media.ready",
      "payload": {
        "media": {
          "duration": 40.207,
          "id": "vpe2p82q64",
          "name": "Lenny Delivers Video!",
          "thumbnail": {
            "url": "https://embed-ssl.wistia.com/deliveries/e96ea382701bc172657d90bf269211beddbf6f7f.jpg?image_crop_resized=200x120"
          },
          "url": "https://harper.wistia.com/medias/vpe2p82q64"
        }
      },
      "metadata": {
        "account_id": "0sxav1wj8o"
      },
      "generated_at": "2024-03-31T21:56:45Z"
    }
  ]
}

media.failed

The media.failed event occurs when processing has failed.

Payload structure

FieldDescription
mediaThe media object

Example delivery

{
  "hook": {
    "uuid": "a4ab9eb6-ab82-4dae-86f2-29f744f7d031"
  },
  "events": [
    {
      "uuid": "fc53f8f78b67d04d455029813f8ec1ef",
      "type": "media.failed",
      "payload": {
        "media": {
          "duration": 40.207,
          "id": "vpe2p82q64",
          "name": "Lenny Delivers Video!",
          "thumbnail": {
            "url": "https://embed-ssl.wistia.com/deliveries/e96ea382701bc172657d90bf269211beddbf6f7f.jpg?image_crop_resized=200x120"
          },
          "url": "https://harper.wistia.com/medias/vpe2p82q64"
        }
      },
      "metadata": {
        "account_id": "0sxav1wj8o"
      },
      "generated_at": "2024-03-31T21:56:45Z"
    }
  ]
}

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": "https://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/aa2863d2bf45cf2cc5c325d129e80bd5c0055883.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      },
      "project": {
        "id": "some-hashed-id",
        "name": "Folder Name",
      },      
      "previous_attributes": {
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        }
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-03-30T15:10:13Z"
  }]
}

media.transcript_updated

A media's transcript is updated when new captions are generated - either automated or human-generated. We'll also send the language code for which caption was updated in case you'd like to grab the transcript via the Captions Show endpoint.

Payload structure

FieldDescription
mediaThe media object
transcript.language_codeThe language code for the transcript that was updated

Example delivery

{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca0142000e7"
  },
  "events": [{
    "uuid": "09e6729eecb3a010",
    "type": "media.transcript_updated",
    "payload": {
      "media": {
        "url": "https://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/aa2863d2bf45cf2cc5c325d129e80bd5c0055883.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      },
      "project": {
        "id": "some-hashed-id",
        "name": "Folder Name",
      },
      "transcript": {
        language_code: "eng",
      },
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-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"
      },
      "project": {
        "id": "some-hashed-id",
        "name": "Folder Name",
      },
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-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": "https://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-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": "https://dave.wistia.com/medias/mmgzi8h6yh",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/23c4846eecd462beab57a508dff7f052a5faf065.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "mmgzi8h6yh",
        "duration": 71.912
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-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": "https://dave.wistia.com/medias/l9dqljgtfy",
        "thumbnail": {
          "url": "https://embed-ssl.wistia.com/deliveries/e04d7729a8b83f4fdd52e107b980f5594359bb45.jpg?image_crop_resized=200x120"
        },
        "name": "Lenny Eating Peanuts",
        "id": "l9dqljgtfy",
        "duration": 71.912
      },
      "email": "[email protected]"
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-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": "https://dave.wistia.com/medias/9xa4r4b4z0",
        "thumbnail": {
          "url": "https://embed-ssl.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": "2024-03-30T15:26:01Z"
  }]
}

viewing_session.annotation.converted

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": "https://dave.wistia.com/medias/9xa4r4b4z0",
        "thumbnail": {
          "url": "https://embed-ssl.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": "2024-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

📝

Note

Custom webhooks are not available on all Zapier Plans. Before you get started be sure that your Zapier account supports them.

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 create zap. You'll see an option to Choose a Trigger App. Within that option, select Webhooks.

Choose Trigger App with Webhooks in Zapier

On the next screen, select the Catch Hook option.

Catch Hook Option in Webhooks in Zapier

From here, you'll need to Pick off a Child Key. For this step, you'll want to add events.payload into the text box. Then click "Continue."

Zapier Events Payload Child Key

Zapier will then generate a catch URL (Your webhook 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).

Wistia Webhook Event Options

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.

After that, you'll get an option to test your webhook. Click "Test Trigger."

Test Webhook in Zapier

To trigger the webhook, you'll want to watch one of your videos in an incognito or private browsing window. That should prompt a 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, and can set it up with various apps.

Choose App to set up Action Zapier takes after receiving Webhook from Wistia

In the "Set up action" section, you'll be able to choose the various information from the webhook you'd like to display.

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

Updated about 1 month ago