Importly

Webhooks

Webhooks let you receive real-time notifications about import and metadata events. Instead of polling status endpoints repeatedly, your system can respond instantly when a job finishes or fails.

Configuring Webhooks

  1. Set a Webhook URL in your Importly dashboard or include webhookUrl in your API requests.
  2. Verify Delivery: We send a POST request to the provided URL when a job completes (or hits an error).

Webhook Event Types

| Event Type | Description | |------------|-------------| | import.completed | Import finished successfully | | import.failed | Import failed | | metadata.completed | Full metadata extraction completed | | metadata.failed | Full metadata extraction failed | | basic-metadata.completed | Basic metadata extraction completed | | basic-metadata.failed | Basic metadata extraction failed |

Payload Structure

Example (Import Completion):

json
1{
2  "jobId": "abc123",
3  "status": "completed",
4  "mediaUrl": "https://cdn.importly.io/abc123/video.mp4",
5  "creditsUsed": 52,
6  "message": "Your video is ready!"
7}

Example (Import Completion with S3 Storage):

When S3 storage is enabled, the webhook payload includes additional S3 information:

json
1{
2  "jobId": "abc123",
3  "status": "completed",
4  "mediaUrl": "https://your-bucket.s3.us-east-1.amazonaws.com/videos/2024/my-video.mp4",
5  "s3Storage": {
6    "url": "https://your-bucket.s3.us-east-1.amazonaws.com/videos/2024/my-video.mp4",
7    "bucket": "your-bucket",
8    "key": "videos/2024/my-video.mp4"
9  },
10  "creditsUsed": 52,
11  "message": "Your video is ready and uploaded to S3!"
12}

Payload Fields

  • jobId: Match this with your internal tracking.
  • status: Could be completed, failed, etc.
  • mediaUrl: Download location (S3 URL if S3 storage is enabled).
  • s3Storage: S3 storage information (only present when S3 storage is enabled).
    • url: Full S3 URL to the uploaded file.
    • bucket: S3 bucket name.
    • key: S3 object key (path within the bucket).
  • creditsUsed: The final cost in credits.

Metadata Webhook Payloads

Example (Full Metadata Completion):

json
1{
2  "success": true,
3  "data": {
4    "jobId": "xyz789",
5    "type": "metadata",
6    "status": "completed",
7    "title": "Sample Video Title",
8    "duration": 300,
9    "thumbnail": "https://i.ytimg.com/vi/xyz789/maxresdefault.jpg",
10    "description": "Video description...",
11    "uploader": "Channel Name",
12    "formats": [...]
13  }
14}

Example (Basic Metadata Completion):

json
1{
2  "success": true,
3  "data": {
4    "jobId": "xyz789",
5    "type": "basic-metadata",
6    "status": "completed",
7    "title": "Sample Video Title",
8    "duration": 300,
9    "thumbnail": "https://i.ytimg.com/vi/xyz789/maxresdefault.jpg"
10  }
11}

The basic metadata webhook payload only includes title, duration, and thumbnail fields.

Security Recommendations

  • Secret Tokens: Configure a secret in your dashboard so each webhook includes a signature header you can verify.
  • HTTPS: Serve your webhook handler over TLS.

Handling Retries

If your webhook endpoint returns a non-2xx status or times out, Importly retries up to a certain limit (e.g., 3 attempts, 1-minute intervals). Implement idempotency in your handlers to handle duplicate notifications gracefully.

Format selectorsS3 Storage Integration