Importly
DocumentationDashboard

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):

{
  "jobId": "abc123",
  "status": "completed",
  "mediaUrl": "https://cdn.importly.io/abc123/video.mp4",
  "creditsUsed": 52,
  "message": "Your video is ready!"
}
  • jobId: Match this with your internal tracking.
  • status: Could be completed, failed, etc.
  • mediaUrl: Download location.
  • 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 selectorsError Handling