Jobs & Webhooks

All generation endpoints are asynchronous. When you submit a request, the API returns a 202 Accepted response with a job_id. There are two ways to track completion: poll the job endpoint, or receive webhook callbacks.

Job Lifecycle

Every job moves through a set of statuses:

Status	Description
`processing`	Job is being processed
`completed`	Job finished successfully -- check output for results
`failed`	Job failed -- check error details

Polling

The simplest way to track a job is to poll the GET /v1/jobs/{job_id} endpoint until the status reaches a terminal state.

1. POST /v2/drone-footage/generate   ->  202 { job_id, status: "processing" }
2. GET  /v1/jobs/{job_id}            ->  200 { status: "processing" }
3. GET  /v1/jobs/{job_id}            ->  200 { status: "completed", output: {...} }

# 1. Submit a job
JOB_ID=$(curl -s -X POST \
  -H "X-API-Key: dome_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Collins St, Melbourne VIC 3000"}' \
  https://api.dometech.com.au/v2/drone-footage/generate \
  | jq -r '.data.job_id')

echo "Job ID: $JOB_ID"

# 2. Poll until complete
while true; do
  RESPONSE=$(curl -s \
    -H "X-API-Key: dome_live_your_key" \
    https://api.dometech.com.au/v1/jobs/$JOB_ID)

  STATUS=$(echo $RESPONSE | jq -r '.data.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo $RESPONSE | jq '.data.output'
    break
  fi

  sleep 5
done

Recommended polling intervals:

Poll every 5 seconds for the first minute
Then every 15 seconds after that
Jobs typically complete within 30 seconds to 3 minutes depending on the operation

Asset Retention

Output URLs (images, videos, audio) point at Dome Tech-hosted storage and remain accessible for 90 days after job completion. After that window the underlying files are deleted; the job record itself (status, metadata, output JSON) is kept indefinitely.

Download and store generated assets on your own infrastructure as soon as a job completes. Treat the URLs in output as a delivery mechanism, not permanent hosting. Follow-up operations that read a parent job's assets (markup edit, markup video) must also happen within the parent's retention window.

Webhooks

Instead of polling, you can receive HTTP POST notifications when jobs complete or fail. Webhooks are ideal for server-to-server integrations.

There are two ways to configure webhooks:

Per-request — Include a webhook_url in any generation request body. The URL must use HTTPS.
Organization-wide — Configure a default webhook URL from your dashboard. This URL will be used for all jobs that don't specify their own.

curl -X POST \
  -H "X-API-Key: dome_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Collins Street, Melbourne VIC 3000",
    "webhook_url": "https://your-server.com/webhooks/dome",
    "callback_metadata": { "internal_id": "prop_456" }
  }' \
  https://api.dometech.com.au/v2/drone-footage/generate

Your webhook endpoint will receive POST requests for these events:

Event	Description
`job.completed`	Job finished successfully (includes output URLs)
`job.failed`	Job failed (includes error details)

Each webhook delivery is an HTTP POST with a JSON body:

{
  "event":  "job.completed",
  "job_id":  "550e8400-e29b-41d4-a716-446655440000",
  "job_type":  "drone_footage",
  "status":  "completed",
  "output":  {
    "video_url":  "https://..."
  },
  "callback_metadata":  {
    "internal_id":  "prop_456"
  },
  "timestamp":  "2026-02-09T10:02:30.000Z"
}

The output field varies by job type. For failed jobs, it contains error details instead.

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request is genuinely from Dome Tech.

Your webhook secret is shown once when you configure your webhook in the dashboard. Store it securely.

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// In your webhook handler:
app.post("/webhooks/dome", (req, res) => {
  const signature = req.headers["x-webhook-signature"] as string;
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.DOME_WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const { event, job_id, output } = req.body;
  // Handle the event...

  res.status(200).send("OK");
});

Always verify the signature before processing webhook payloads. Never trust the payload contents without verification.

Callback Metadata

You can include a callback_metadata object in any generation request. This opaque object is stored with the job and returned in all webhook payloads, allowing you to correlate events with your internal records without additional lookups.

// In your request:
{
  "address":  "123 Collins Street, Melbourne VIC 3000",
  "webhook_url":  "https://your-server.com/webhooks/dome",
  "callback_metadata":  {
    "listing_id":  "lst_789",
    "user_id":  "usr_123",
    "source":  "bulk_import"
  }
}

// Returned in every webhook payload:
{
  "event":  "job.completed",
  "job_id":  "...",
  "callback_metadata":  {
    "listing_id":  "lst_789",
    "user_id":  "usr_123",
    "source":  "bulk_import"
  }
}

Edit Workflows

Some tools support editing after the initial generation completes. Edit workflows create a new child job (with its own job_id) that references the parent. See the Markup Creator guide for a full example.

Listing Jobs

You can list all jobs with optional filters:

# All jobs
curl -H "X-API-Key: dome_live_your_key" \
  https://api.dometech.com.au/v1/jobs

# Filter by status
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.dometech.com.au/v1/jobs?status=completed"

# Filter by job type
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.dometech.com.au/v1/jobs?job_type=drone_footage"

# Pagination
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.dometech.com.au/v1/jobs?limit=10&offset=0"

Job Response Shape

{
  "data":  {
    "id":  "550e8400-e29b-41d4-a716-446655440000",
    "job_type":  "drone_footage",
    "status":  "completed",
    "input":  {
      "address":  "123 Collins St, Melbourne VIC 3000"
    },
    "output":  {
      "video_url":  "https://storage.domeagent.com.au/..."
    },
    "created_at":  "2026-02-09T10:00:00.000Z",
    "updated_at":  "2026-02-09T10:01:30.000Z",
    "completed_at":  "2026-02-09T10:01:30.000Z"
  },
  "meta":  {
    "request_id":  "req_abc123",
    "timestamp":  "2026-02-09T10:01:30.000Z"
  }
}