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

### Create an endpoint

```bash theme={null}
curl -X POST https://api.tella.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_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>

### Delete an endpoint

```bash theme={null}
curl -X DELETE https://api.tella.com/v1/webhooks/endpoints/{id} \
  -H "Authorization: Bearer YOUR_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 YOUR_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 YOUR_API_KEY"
```

### Get a specific message

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

## Event types

See the [Webhooks API Reference](/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>