Webhooks

Webhooks let you receive a notification when a job reaches a terminal state (completed, failed, rejected, or cancelled). Instead of polling GET /api/v1/jobs/:id, Xora sends a POST to your URL with the job result.

Setting a webhook

Per-job webhook

Add webhookUrl to your job creation request:

cURL

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": { "url": "https://example.com/video.mp4" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress", "crf": 28 },
    "webhookUrl": "https://your-server.com/webhooks/xora"
  }'

Node.js

const response = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'recipe',
    input: { url: 'https://example.com/video.mp4' },
    output: { format: 'mp4' },
    recipe: { name: 'compress', crf: 28 },
    webhookUrl: 'https://your-server.com/webhooks/xora'
  })
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "recipe",
        "input": { "url": "https://example.com/video.mp4" },
        "output": { "format": "mp4" },
        "recipe": { "name": "compress", "crf": 28 },
        "webhookUrl": "https://your-server.com/webhooks/xora"
    }
)
data = response.json()
print(data)

Default webhook

You can set a default webhook URL that’s used for all jobs that don’t specify their own webhookUrl:

cURL

curl -X POST https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultWebhookUrl": "https://your-server.com/webhooks/xora"
  }'

Node.js

const response = await fetch('https://api.xora.sh/v1/settings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    defaultWebhookUrl: 'https://your-server.com/webhooks/xora'
  })
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "defaultWebhookUrl": "https://your-server.com/webhooks/xora"
    }
)
data = response.json()
print(data)

When a job includes a webhookUrl, it overrides the default. When it doesn’t, the default is used.

Webhook payload

When a job reaches a terminal state, Xora sends a POST request to your URL with this JSON body:

{
  "data": {
    "jobId": "01JXYZ1234ABCDEF56789000",
    "state": "completed",
    "progress": 100,
    "output": {
      "signedUrl": "https://cdn.xora.sh/...signed-url..."
    },
    "output_files": {
      "output": {
        "file_id": "01JXYZ...-output",
        "filename": "output.mp4",
        "size_mbytes": 12.5,
        "duration": 120.5,
        "file_type": "video",
        "file_format": "mp4",
        "mime_type": "video/mp4",
        "codec": "h264",
        "width": 1920,
        "height": 1080,
        "storage_url": "https://cdn.xora.sh/...signed-url..."
      }
    }
  },
  "timestamp": 1717500000000
}

Failed job payload

{
  "data": {
    "jobId": "01JXYZ1234ABCDEF56789000",
    "state": "failed",
    "progress": 35,
    "error": {
      "code": "TRANSCODE_ERROR",
      "message": "FFmpeg exited with code 1",
      "stage": "transcoding",
      "retryable": true
    }
  },
  "timestamp": 1717500000000
}

Payload fields

Field	Type	Description
data.jobId	string	The job ID
data.state	string	Terminal state: completed, failed, rejected, cancelled
data.progress	number	Progress at time of completion (100 for completed)
data.output	object	Signed URL for single-output jobs
data.outputs	object	Signed URLs for multi-output jobs
data.output_files	object	Detailed file metadata per output
data.error	object	Error details (only present on failure)
timestamp	number	Unix timestamp in milliseconds

Requirements

Caution

Webhook URLs must meet these requirements:

• Must use HTTPS (https://...)
• Must not target private/localhost addresses (127.0.0.1, 10.*, 192.168.*, 172.16.*, 169.254.*, *.local)

Retry behavior

If your endpoint returns a non-2xx response or is unreachable, Xora retries the webhook with exponential backoff:

Attempt	Delay after failure
1st	Immediate
2nd	500ms
3rd	1 second

After 3 failed attempts, the webhook is abandoned. The job result is still available via GET /api/v1/jobs/:id.

Tip

Always return a 200 OK quickly from your webhook handler. Do your processing asynchronously — if your endpoint takes too long, the retry may fire unnecessarily.

Testing your webhook

Use the webhook test endpoint to send a sample payload to your configured default URL:

cURL

curl -X POST https://api.xora.sh/v1/settings/webhook/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const response = await fetch('https://api.xora.sh/v1/settings/webhook/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.xora.sh/v1/settings/webhook/test",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)

Success response

{
  "ok": true,
  "status": 200
}

Failure response

{
  "ok": false,
  "status": 500
}

Note

The test endpoint sends a sample completed job payload with test data. It only works when you have a defaultWebhookUrl configured in your settings.

Checking your settings

Read your current webhook configuration:

cURL

curl https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const response = await fetch('https://api.xora.sh/v1/settings', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)

{
  "defaultWebhookUrl": "https://your-server.com/webhooks/xora",
  "defaultStorageProviderId": null,
  "updatedAt": "2026-06-04T10:00:00.000Z"
}

Clearing the default webhook

Set defaultWebhookUrl to null:

cURL

curl -X PUT https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "defaultWebhookUrl": null }'

Node.js

const response = await fetch('https://api.xora.sh/v1/settings', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    defaultWebhookUrl: null
  })
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.put(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "defaultWebhookUrl": None
    }
)
data = response.json()
print(data)