Importly

Webhooks

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

Configuring Webhooks

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

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.

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