Webhooks

Advanced: Webhooks

Webhooks provide a robust mechanism for receiving real-time updates about asynchronous operations (like model training, image/video generation) without resorting to inefficient polling.

Overview

1. Configure Endpoint: Provide a secure HTTPS URL in your REALM AI account settings where you can receive POST requests.

2. Receive Events: When a job you initiated changes state (e.g., processing -> completed, queued -> failed), REALM AI sends a JSON payload to your configured URL.

3. Verify Signature: (Recommended) Each webhook request should include a signature in its headers (e.g., X-Webhook-Signature). You can verify this signature using a shared secret (provided in your account settings) to ensure the request originated from REALM AI.

4. Process Payload: Extract information like jobId, status, results (if completed), or errorCode (if failed) from the JSON payload and update your application state accordingly.

5. Respond Quickly: Acknowledge receipt of the webhook immediately with a 2xx status code (e.g., 200 OK or 202 Accepted). Perform time-consuming processing asynchronously to avoid timeouts.

Payload Structure (Example - Job Completion)

{
  "eventId": "evt_webhook_12345",
  "eventType": "job.completed", // e.g., job.processing, job.failed, model.training.completed
  "apiVersion": "v1",
  "createdAt": "2024-03-10T15:06:15Z",
  "data": {
    "object": "job",
    "jobId": "job_img_gen_123",
    "jobType": "image_generation",
    "status": "completed",
    "results": [
      {
        "imageId": "img_abc",
        "url": "https://cdn.realm.ai/images/img_abc.png",
        "seed": 123456789
      }
    ],
    "completedAt": "2024-03-10T15:06:10Z"
    // ... other relevant job metadata
  }
}

Best Practices

• Security: Always use HTTPS for your endpoint and verify webhook signatures.

• Idempotency: Handle potential duplicate webhook deliveries gracefully (e.g., using the eventId).

• Error Handling: Implement robust error handling and logging for webhook processing.

• Responsiveness: Respond to webhooks within a few seconds to avoid retries from REALM AI.

(Detailed configuration steps and signature verification examples will be provided here.)