> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when events happen in your workspace

# Webhooks

Webhooks allow your application to receive real-time HTTP notifications when events occur in your Tella workspace. Instead of polling the API for changes, webhooks push updates to your server as they happen.

## Setting up webhooks

1. Sign in to [Tella](https://www.tella.tv)
2. Navigate to **Settings** > **Webhooks**
3. Add your endpoint URL and select the events you want to receive

## Managing webhooks via API

In addition to the web interface, you can manage webhook endpoints programmatically through the API.

Webhook endpoints are scoped to the authenticated API key's user, not shared across the workspace. Events are routed to the user context that emits them. In particular, `playlist.video_added` is delivered to the user who adds the video, who may be a playlist editor rather than its owner.

### Create an endpoint

```bash theme={null}
curl -X POST https://api.tella.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/tella",
    "filterTypes": ["video.created", "export.ready"]
  }'
```

Response:

```json theme={null}
{
  "id": "ep_abc123def456",
  "secret": "whsec_xyz789..."
}
```

<Warning>
  The signing secret is only returned once when creating the endpoint. Store it
  securely.
</Warning>

### List endpoints

```bash theme={null}
curl "https://api.tella.com/v1/webhooks/endpoints?limit=20" \
  -H "Authorization: Bearer $TELLA_API_KEY"
```

Use the response's `nextCursor` as the `cursor` query parameter to retrieve the next page.

### Update an endpoint

Only include the fields you want to change. You can update the delivery URL, subscribed event types, or pause delivery with `disabled`.
Set `filterTypes` to `null` to remove event filtering and deliver every event type.

```bash theme={null}
curl -X PATCH https://api.tella.com/v1/webhooks/endpoints/{id} \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filterTypes": ["video.created", "export.ready"],
    "disabled": false
  }'
```

### Delete an endpoint

```bash theme={null}
curl -X DELETE https://api.tella.com/v1/webhooks/endpoints/{id} \
  -H "Authorization: Bearer $TELLA_API_KEY"
```

### Get endpoint secret

If you need to retrieve the signing secret again:

```bash theme={null}
curl https://api.tella.com/v1/webhooks/endpoints/{id}/secret \
  -H "Authorization: Bearer $TELLA_API_KEY"
```

### List recent messages

View recently sent webhook messages for debugging:

```bash theme={null}
curl "https://api.tella.com/v1/webhooks/messages?limit=10&event_types=video.created" \
  -H "Authorization: Bearer $TELLA_API_KEY"
```

### Get a specific message

```bash theme={null}
curl https://api.tella.com/v1/webhooks/messages/{id} \
  -H "Authorization: Bearer $TELLA_API_KEY"
```

## Event types

See the [Webhooks API Reference](/docs/api-reference/videos/video-created) for detailed payload schemas for each event type:

* **video.created** - New video created in workspace
* **video.viewed** - A view was received on one of your videos (includes the all-time view rank)
* **video.milestone** - A video crossed a view-count threshold of 1, 5, 10, 25, 50, 100, or 500
* **export.ready** - Video export completed and ready for download
* **transcript.ready** - Video transcript generated and ready
* **playlist.created** - New playlist created in workspace
* **playlist.video\_added** - Video added to a playlist

## Webhook delivery

Webhooks are delivered as HTTP POST requests to your configured endpoint with the event payload as JSON in the request body.

### Retry policy

If your endpoint returns a non-2xx status code, delivery will be automatically retried with exponential backoff.

### Timeout

Your endpoint must respond within 30 seconds. If it times out, the delivery will be retried.

## Verifying signatures

All webhook requests are signed to ensure authenticity. You should verify the signature before processing any webhook.

The signature is included in the following headers:

* `svix-id` - Unique message identifier
* `svix-timestamp` - Unix timestamp of when the message was sent
* `svix-signature` - The signature to verify

Your webhook signing secret can be found in **Settings** > **Webhooks** under your endpoint configuration.

For signature verification, you can use the [Svix webhook verification libraries](https://docs.svix.com/receiving/verifying-payloads/how) available for most languages.

## Best practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a 2xx response as soon as you receive the webhook. Process the payload
    asynchronously if needed to avoid timeouts.
  </Accordion>

  {" "}

  <Accordion title="Handle duplicates">
    Webhooks may occasionally be delivered more than once. Use event-specific IDs
    to deduplicate.
  </Accordion>

  {" "}

  <Accordion title="Verify signatures">
    Always verify the webhook signature before processing to ensure the request is
    authentic and hasn't been tampered with.
  </Accordion>

  <Accordion title="Use HTTPS">
    Only configure HTTPS endpoints to ensure webhook payloads are encrypted in transit.
  </Accordion>
</AccordionGroup>