---
updatedAt: 2026-07-22T19:58:53.000Z
agentTools:
  projectIndex: https://docs.wistia.com/llms.txt
---

# 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 Wistia Form? 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](#connecting-to-zapier-example) 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](https://my.wistia.com/account/webhooks). Or, read on for more information about the [available event types](#events) and the structure of the data.

## 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](http://ruby-doc.org/stdlib-2.1.0/libdoc/openssl/rdoc/OpenSSL/HMAC.html) 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

```rb
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](#events) for details on each one.

### Example POST

```js
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"
  }]
}

```

<Callout icon="📘" theme="info">
  ### Note

  The "duration" value is displayed in seconds.
</Callout>

## Events

<Callout icon="🙌" theme="default">
  ### Tip

  Webhooks are currently available for the following events in Wistia. We plan on adding more, so please [let us know](https://wistia.com/support/contact?form=support) 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.
</Callout>

### List of Events

* [media.created](#media-created)
* [media.processing](#media-processing)
* [media.ready](#media-ready)
* [media.failed](#media-failed)
* [media.updated](#media-updated)
* [media.transcript\_updated](#media-transcript_updated)
* [media.transcript\_failed](#media-transcript_failed)
* [media.deleted](#media-deleted)
* [media.translation\_created](#media-translation_created)
* [media.localization\_created](#media-localization_created)
* [media.localization\_failed](#media-localization_failed)
* [viewing\_session.play](#viewing_session-play)
* [viewing\_session.percent\_watched](#viewing_session-percent_watched)
* [viewing\_session.turnstile.converted](#viewing_session-turnstile-converted)
* [viewing\_session.call\_to\_action.converted](#viewing_session-call_to_action-converted)
* [viewing\_session.annotation.converted](#viewing_session-annotation-converted)
* [live\_event.registration](#live_event-registration)

### media.created

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

#### Payload structure

| Field | Description      |
| ----- | ---------------- |
| media | The media object |

#### Example delivery

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

| Field | Description      |
| ----- | ---------------- |
| media | The media object |

#### Example delivery

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

| Field | Description      |
| ----- | ---------------- |
| media | The media object |

#### Example delivery

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

| Field | Description      |
| ----- | ---------------- |
| media | The media object |

#### Example delivery

```json
{
  "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 it is replaced or 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](https://docs.wistia.com/reference/getting-started-with-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

```json
{
  "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](https://docs.wistia.com/reference/get_medias-media-hashed-id-captions-language-code-json) endpoint.

#### Payload structure

| Field                     | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| media                     | The media object                                      |
| transcript.language\_code | The language code for the transcript that was updated |

#### Example delivery

```json
{
  "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": {
        "hashed_id": "htb93bq6g79crsvk",
        "language_code": "eng",
      },
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-03-30T15:10:13Z"
  }]
}

```

### media.transcript\_failed

The `media.transcript_failed` event occurs when transcript generation has failed for a media.

#### Payload structure

| Field                     | Description                                      |
| ------------------------- | ------------------------------------------------ |
| media                     | The media object                                 |
| transcript.hashed\_id     | The ID of the transcript that failed             |
| transcript.language\_code | The language code for the transcript that failed |
| transcript.reason         | The reason for the failure (if available)        |

#### Example delivery

```json
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca0142000e7"
  },
  "events": [{
    "uuid": "09e6729eecb3a010",
    "type": "media.transcript_failed",
    "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": {
        "hashed_id": "htb93bq6g79crsvk",
        "language_code": "eng",
        "reason": "Transcription service unavailable"
      }
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-03-30T15:10:13Z"
  }]
}

```

### media.deleted

#### Payload structure

| Field | Description                       |
| ----- | --------------------------------- |
| media | The media object that was deleted |

#### Example delivery

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

```

### media.translation\_created

| Field      | Description                                     |
| ---------- | ----------------------------------------------- |
| media      | The media object that had a translation created |
| transcript | The translated object of translation            |
| project    | The project the media belongs to                |

```json
{
  "hook": {
    "uuid": "138f2d1e-c532-42cb-a3f0-b4ec9c821fca"
  },
  "events": [
    {
      "uuid": "c136ce21d52f0597a5c7287d51d9ab6c",
      "type": "media.translation_created",
      "payload": {
        "media": {
          "duration": 60.9667,
          "id": "atdbn4yc17",
          "name": "short-video-guitar",
          "thumbnail": {
            "url": "http://embed-cloudfront.wistia.st/deliveries/452e61f4ac99c31fe9560466583aea4f15243b5a.jpg?image_crop_resized=200x120"
          },
          "url": "https://account-g1l6efm4sos862r8woo9r9dscjm3geuv.wistia.io/medias/atdbn4yc17"
        },
        "project": {
          "id": "8oecqbe5e9",
          "name": "My First Folder"
        },
        "transcript": {
					"hashed_id": "htb93bq6g79crsvk",
          "iso639_2_language_code": "bn",
          "language_code": "ben",
          "language_name": "Bengali",
          "language_native_name": "বাংলা",
          "transcript_text": "ঠিক আছে। এই বিষয়ে আমি এখনই কথা বলছি। আমি আমার গিটারের বিষয়টি নির্দিষ্ট করার চেষ্টা করছি।\n\nসুতরাং আমি যদি একাদশ, দ্বাদশ, ত্রয়োদশ, চতুর্দশ খেলতে পারি, তাহলে কোনো গুজা নেই। কিন্তু আমি যদি নমন শুরু করি, একবার এখানে ত্রয়োদশ ফ্রেট বেঙ্ক করলে তা চলে যায়। এবং দ্বাদশ ফ্রেটের একই বাঁকটি ঠিক আছে।\n\nসম্ভবত কিছুটা ঝাঁকুনি, তবে এটি আমার জন্য একটি সমস্যা হওয়ার জন্য যথেষ্ট নয়। এবং চতুর্দশ ফ্রেটের ক্ষেত্রেও একই রকম।\n\nএকটু বাজ।\n\nএবং এর পরে, এটি ঠিক আছে। কোনও বুজিং নেই। এবং কিছুটা বাজ ঠিক আছে, তবে চোক আউট কিছুটা দুর্ভাগ্যজনক।\n\nএটি বি স্ট্রিংটিতে অনেক ভাল বলে মনে হচ্ছে, তবে ই স্ট্রিংটিতে এটি খুব, খুব লক্ষণীয়।\n\nএবং আপনি এটি প্রায় শুনতে পেরেছিলেন, যেমন, অন্য কোনও ফ্রেটে জড়িত হন।\n\nসুতরাং, এটাই সমস্যা।"
        }
      },
      "metadata": {
        "account_id": "qfq2o29zpk"
      },
      "generated_at": "2025-07-17T20:10:44Z"
    }
  ]
}
```

### media.localization\_created

| Field        | Description                                    |
| ------------ | ---------------------------------------------- |
| media        | The media object that had localization created |
| localization | The localization object                        |
| project      | The project the media belongs to               |

#### Example delivery

```json
{
  "hook": {
    "uuid": "138f2d1e-c532-42cb-a3f0-b4ec9c821fca"
  },
  "events": [
    {
      "uuid": "5bd97e7547a9407678bd250b5fcda2b3",
      "type": "media.localization_created",
      "payload": {
        "localization": {
          "created_at": "2025-07-17T20:02:18+00:00",
          "enabled": true,
          "enabled_at": "2025-07-17T20:08:28+00:00",
          "hashed_id": "1f6s56q55e",
          "iso639_2_language_code": "ar-IQ",
          "language_code": "ar-IQ",
          "language_name": "Arabic (Iraq)",
          "native_language_name": "العربية (العراق)",
          "ordered_at": "2025-07-17T20:02:18+00:00",
          "source_media": {
            "created_at": "2025-07-17T18:57:59+00:00",
            "duration": 60.9667,
            "hashed_id": "atdbn4yc17",
            "name": "short-video-guitar",
            "updated_at": "2025-07-17T18:59:04+00:00"
          },
          "transcript": {
            "created_at": "2025-07-17T20:05:56+00:00",
            "hashed_id": "htb93bq6g79crsvk",
            "language_name": "Arabic (Iraq)",
            "native_language_name": "العربية (العراق)",
            "text": "حسنا. هذا ما أتحدث عنه الآن. أحاول أن أحدد مشكلة قيثاري.\n\nلذلك إذا لعبت في الحادي عشر والثاني عشر والثالث عشر والرابع عشر، فلن يكون هناك أي ضجيج. ولكن إذا بدأت في الانحناء، فبمجرد أن أقوم بالانحناء الثالث عشر هنا، سيختنق الأمر. ونفس الانحناء على القدم الثانية عشرة جيد.\n\nربما القليل من الضجيج، لكن ليس كافيًا ليكون مشكلة بالنسبة لي. ونفس الشيء مع الحنق الرابع عشر.\n\nالقليل من الضجيج.\n\nوبعد ذلك، لا بأس. لا أزيز. والقليل من الضجيج لا بأس به، لكن الاختناق أمر مؤسف بعض الشيء.\n\nيبدو الأمر أفضل كثيرًا في السلسلة b، ولكن في السلسلة e، يكون ملحوظًا جدًا.\n\nويمكنك سماع ذلك تقريبًا، مثل الانخراط في غضب آخر.\n\nإذن، هذه هي المشكلة.",
            "updated_at": "2025-07-17T20:05:57+00:00"
          },
          "updated_at": "2025-07-17T20:08:15+00:00"
        },
        "media": {
          "duration": 60.9667,
          "id": "atdbn4yc17",
          "name": "short-video-guitar",
          "thumbnail": {
            "url": "http://embed-cloudfront.wistia.st/deliveries/452e61f4ac99c31fe9560466583aea4f15243b5a.jpg?image_crop_resized=200x120"
          },
          "url": "https://account-g1l6efm4sos862r8woo9r9dscjm3geuv.wistia.io/medias/atdbn4yc17"
        },
        "project": {
          "id": "8oecqbe5e9",
          "name": "My First Folder"
        }
      },
      "metadata": {
        "account_id": "qfq2o29zpk"
      },
      "generated_at": "2025-07-17T20:08:28Z"
    }
  ]
}
```

### media.localization\_failed

The `media.localization_failed` event occurs when localization has failed for a media.

#### Payload structure

| Field                       | Description                                        |
| --------------------------- | -------------------------------------------------- |
| media                       | The media object                                   |
| localization.hashed\_id     | The ID of the localization that failed             |
| localization.language\_code | The language code for the localization that failed |
| project                     | The project the media belongs to                   |

#### Example delivery

```json
{
  "hook": {
    "uuid": "138f2d1e-c532-42cb-a3f0-b4ec9c821fca"
  },
  "events": [
    {
      "uuid": "5bd97e7547a9407678bd250b5fcda2b3",
      "type": "media.localization_failed",
      "payload": {
        "localization": {
          "hashed_id": "1f6s56q55e",
          "language_code": "ar-IQ",
          "language_name": "Arabic (Iraq)"
        },
        "media": {
          "duration": 60.9667,
          "id": "atdbn4yc17",
          "name": "short-video-guitar",
          "thumbnail": {
            "url": "http://embed-cloudfront.wistia.st/deliveries/452e61f4ac99c31fe9560466583aea4f15243b5a.jpg?image_crop_resized=200x120"
          },
          "url": "https://account-g1l6efm4sos862r8woo9r9dscjm3geuv.wistia.io/medias/atdbn4yc17"
        },
        "project": {
          "id": "8oecqbe5e9",
          "name": "My First Folder"
        }
      },
      "metadata": {
        "account_id": "qfq2o29zpk"
      },
      "generated_at": "2025-07-17T20:08:28Z"
    }
  ]
}
```

### 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                                  |

<Callout icon="📝" theme="default">
  ### Note

  In the [Stats API](https://docs.wistia.com/reference/getting-started-with-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 🔮.
</Callout>

#### Example delivery

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

| Field            | Description                                   |
| :--------------- | :-------------------------------------------- |
| visitor          | The visitor who watched the video             |
| email            | The email address of the visitor, if provided |
| name             | The name of the visitor, if provided          |
| viewing\_session | The viewing\_session object                   |
| percent\_watched | The percent\_watched threshold reached        |
| media            | The media object                              |

<Callout icon="📘" theme="info">
  ### Note

  The email and name fields will only appear if the percent watched is in the same session as a Wistia Form submission.
</Callout>

#### Example delivery

```json
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e67473ecb3a000",
    "type": "viewing_session.percent_watched",
    "payload": {
      "visitor": {
        "email": "lenny@wistia.com",
        "id": "v20150227_bee7121c-04bb-42ae-abc9-5327f536df0f",
        "name": "Lenny Lavigne"
      },
      "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 [Wistia Forms](https://wistia.com/product/turnstile).

#### Payload structure

| Field            | Description                                                                        |
| ---------------- | ---------------------------------------------------------------------------------- |
| visitor          | The visitor object for the visitor who submitted their information to Wistia Forms |
| viewing\_session | The viewing\_session object                                                        |
| name             | The name of the visitor, if provided                                               |
| media            | The media object for the media the Wistia Form is on                               |
| email            | The email address of the visitor                                                   |

#### Example delivery

```json
{
  "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": "lenny@wistia.com"
    },
    "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](https://wistia.com/product/player#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

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

| 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

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

```

### live\_event.registration

The `live_event.registration` event occurs when someone registers for a live event.

#### Payload structure

| Field                       | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| live\_event                 | The live event object                                |
| live\_event.id              | The hashed ID of the live event                      |
| live\_event.name            | The title of the live event                          |
| live\_event.url             | The URL of the live event                            |
| live\_event.starts\_at      | When the live event is scheduled to start (ISO-8601) |
| registration                | The registration details                             |
| registration.visitor\_key   | The unique identifier for the visitor                |
| registration.registered\_at | When the registration occurred (ISO-8601)            |
| registration.fields         | The form fields submitted during registration        |
| location                    | Geographic location information of the registrant    |
| utm                         | UTM parameters captured during registration          |
| referrer\_url               | The URL the registrant came from                     |

#### Example delivery

```json
{
  "hook": {
    "uuid": "bb812395-8d23-4285-9278-9ca014209ae7"
  },
  "events": [{
    "uuid": "09e7b27100b3a000",
    "type": "live_event.registration",
    "payload": {
      "live_event": {
        "id": "abc123xyz",
        "name": "Product Launch Webinar",
        "url": "https://company.wistia.com/live/abc123xyz",
        "starts_at": "2024-04-15T14:00:00Z"
      },
      "registration": {
        "visitor_key": "v20150227_c651bc81-8ec8-445b-b8a0-878d19278d35",
        "registered_at": "2024-03-31T13:59:22Z",
        "fields": {
          "first_name": "Lenny",
          "last_name": "Lavigne",
          "email": "lenny@wistia.com",
          "company": "Wistia",
          "job_title": "Video Producer",
          "phone": "+1-555-123-4567",
          "country": "United States"
        }
      },
      "location": {
        "country": "United States",
        "region": "Massachusetts",
        "city": "Cambridge"
      },
      "utm": {
        "campaign": "spring_launch",
        "medium": "email",
        "source": "newsletter"
      },
      "referrer_url": "https://wistia.com/blog/product-update"
    },
    "metadata": {
      "account_id": "8lq25o0p9c"
    },
    "generated_at": "2024-03-31T13:59:22Z"
  }]
}

```

## 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

<Callout icon="📝" theme="default">
  ### Note

  Custom webhooks are _not_ available on all [Zapier Plans](https://zapier.com/pricing). Before you get started be sure that your Zapier account supports them.
</Callout>

One of the easiest ways to use Wistia's webhooks is to set up a zap with [Zapier](https://zapier.com). You can begin by [setting up your own Zapier account](https://zapier.com/sign-up/) 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](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_1.png)

On the next screen, select the *Catch Hook* option.

![Catch Hook Option in Webhooks in Zapier](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_2.png)

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 ](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_3.png)

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](https://my.wistia.com/account/webhooks), 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](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_4.png)

Next up, select the events you're interested in sending to your zap. Check the [events](#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](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_5.png)

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](https://dl33gfp95tkep.cloudfront.net/webhooks/zapier_screen_6.png)

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!