Skip to main content

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Move API account, such as job completion or processing status changes.

Overview​

Webhooks provide a way to integrate Move API events into your applications without polling the API. When configured, Move API will send HTTP POST requests to your specified endpoint whenever relevant events occur.

Supported events​

Job events​

  • job.created: A new job has been created
  • job.processing: Job processing has started
  • job.completed: Job processing has completed successfully
  • job.failed: Job processing has failed
  • job.cancelled: Job has been cancelled

Take events​

  • take.ready: Take data is ready for download
  • take.deleted: Take has been deleted

Webhook configuration​

Create webhook​

POST /api/webhooks
{
  "url": "https://your-app.com/webhooks/move",
  "events": ["job.completed", "job.failed"],
  "description": "Production webhook for job notifications"
}

Webhook response​

{
  "id": "webhook_123",
  "url": "https://your-app.com/webhooks/move",
  "events": ["job.completed", "job.failed"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Event payload​

Job completed event​

{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "job_id": "job_456",
    "take_id": "take_789",
    "model": "s1",
    "duration": 5.2,
    "frame_count": 156
  }
}

Job failed event​

{
  "event": "job.failed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "job_id": "job_456",
    "error": "Video file corrupted",
    "error_code": "VIDEO_CORRUPTED"
  }
}

Security​

Webhook signatures​

All webhook requests include a signature header for verification:

X-Move-Signature: sha256=abc123...

Signature verification​

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(f"sha256={expected}", signature)

Best practices​

Endpoint requirements​

  • HTTPS only: Webhook endpoints must use HTTPS
  • Quick response: Respond within 5 seconds
  • Idempotency: Handle duplicate events gracefully
  • Error handling: Return appropriate HTTP status codes

Retry logic​

Move API will retry failed webhook deliveries:

  • Retry schedule: 1min, 5min, 15min, 1hour, 6hours, 24hours
  • Max retries: 6 attempts
  • Timeout: 10 seconds per attempt

Monitoring​

  • Log all events: Keep records of received webhooks
  • Monitor failures: Track failed deliveries
  • Health checks: Verify endpoint availability

API endpoints​

List webhooks​

GET /api/webhooks

Get webhook details​

GET /api/webhooks/{webhook_id}

Update webhook​

PUT /api/webhooks/{webhook_id}

Delete webhook​

DELETE /api/webhooks/{webhook_id}

Test webhook​

POST /api/webhooks/{webhook_id}/test

Next steps​