Skip to main content

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

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: 
{
  "id": "ep_abc123def456",
  "secret": "whsec_xyz789..."
}
The signing secret is only returned once when creating the endpoint. Store it securely.

​
Delete an endpoint

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: 
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: 
curl "https://api.tella.com/v1/webhooks/messages?limit=10&event_types=video.created" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get a specific message

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

​
Event types

See the Webhooks API Reference for detailed payload schemas for each event type:
  • video.created - New video created in workspace
  • 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 available for most languages.

​
Best practices

Return a 2xx response as soon as you receive the webhook. Process the payload asynchronously if needed to avoid timeouts.
Webhooks may occasionally be delivered more than once. Use event-specific IDs to deduplicate.
Always verify the webhook signature before processing to ensure the request is authentic and hasn’t been tampered with.
Only configure HTTPS endpoints to ensure webhook payloads are encrypted in transit.