---
url: https://docs.seen.io/api/external-events.md
description: >-
  Documents the workspace webhook that sends real-time HTTP requests when a
  viewer plays, watches, opens, shares, or clicks a CTA in a Seen player.
---

# External Events

External Events allows you to configure a webhook that sends real-time HTTP requests to your systems whenever a viewer interacts with a Seen player. This is useful for triggering downstream workflows, analytics pipelines, CRM updates, or any other system that needs to react to viewer activity.

![External Events settings in a Seen workspace](/images/api-external-events-feature.png)

Navigate to **Settings** ⇒ **External Events** to configure your workspace webhook.

## Enabling the Webhook

Use the **Enabled** toggle at the top of the form to activate or deactivate the webhook. When disabled, no requests will be sent regardless of the configuration below.

All configuration fields below are only accessible when the webhook is enabled.

## General

### HTTP Method

Select the HTTP method to use for the outgoing request. Supported methods: `GET` `POST` `PUT` `PATCH`

### Endpoint URL

The URL of the endpoint that will receive the webhook request.

### Subscribed Events

Select one or more events that should trigger the webhook. A request will be sent each time one of the selected events occurs.

| Event | Description |
|---|---|
| `video-played` | Fired when the video starts playing from the beginning. Resuming a paused video **does not** trigger this event. It will fire again if the player is reloaded and playback is started fresh. |
| `video-watched` | Fired when a viewer has watched at least **80%** of the video. |
| `player-opened` | Fired when the Seen player is opened or loaded by the viewer, regardless of whether playback starts. |
| `share-clicked` | Fired when the viewer clicks the share button inside the player. |
| `cta-clicked` | Fired when the viewer clicks a Call-to-Action element within the player. |

## Headers

Add custom HTTP headers to the webhook request as key-value pairs. Click **Add Header** to add a new row. Remove a header using the trash icon next to it.

A `Content-Type: application/json` header is included by default.

## Authentication

Expand the **Authentication** section to configure how the webhook request is authenticated.

If you have already added authentication credentials manually in the Headers section, you can leave this set to **None**.

### None

No authentication header will be added to the request. Use this for endpoints that are open or that handle authentication via other means (e.g. IP allowlisting, signed URLs).

### Bearer Token

Adds an `Authorization: Bearer <token>` header to the request.

* **Token**: The bearer token value. Supports dynamic Workspace properties and event outputs.

### API Key

Adds a custom header containing your API key.

* **Header Name**: The name of the header (e.g. `X-API-Key`)
* **Header Value**: The API key value. Supports dynamic Workspace properties and event outputs.

## Payload Configuration

Define the full JSON body that will be sent with the request. Write the payload as a JSON template in the **Payload Template** field.

You can insert dynamic values using the variable picker. Two categories of dynamic values are available:

**Variables**: All Workspace properties, the same ones used to personalise your videos.

**Outputs**: Event-specific values generated during video rendering:

| Output | Description |
|---|---|
| `playerId` | The unique identifier of the player instance that triggered the event. |
| `playerLink` | The full URL of the personalised player page for the viewer. |
| `eventType` | The name of the event that was fired (e.g. `video-played`). |

A **Payload Preview** is shown below the editor so you can verify the JSON is valid before saving.

## Saving and Deleting

* Click **Create Webhook** to save a new configuration.
* Click **Update Webhook** to apply changes to an existing configuration.
* Click **Delete** to permanently remove the webhook. You will be asked to confirm before deletion.
* Click **Cancel** to discard any unsaved changes.

Only one webhook configuration is supported per workspace at the moment.