Integration

Viewer

Integrate Viewer into your platform using our SDKs to automate study creation and management. This is for IT personnel of PACS infrastructure.

Introduction

Note: This integration guide is specifically for the Viewer platform. It is not intended for AutoScribe or the Clinical Platform integrations.

Studies can be fully created and managed using the Viewer dashboard, but automating and baking Viewer into your platform makes the entire process streamlined and more efficient. Additionally, any sort of study viewing requires integrations to provide seamless access to studies within your existing workflow.

This guide covers the essential integration patterns for developers, walking you through the complete setup process from initial configuration to production deployment. For complete API documentation and all available operations, see the API Reference.

Integration Steps

To integrate Viewer into your platform, follow these steps:

Create API key — Generate an API key in the Viewer dashboard with appropriate permissions and scopes for your integration needs.
Configure webhooks — Set up webhook endpoints to handle study image access requests (if using the viewer), ensuring secure signature verification.
Automate creating studies — Use our SDKs to programmatically create studies from your PACS, RIS, or other systems, enabling seamless workflow integration (manual creation in dashboard also supported).
Invite your users — Set up user access and authentication to allow your team members to access Viewer studies.

API Configuration

Before integrating Viewer into your platform, you need to create and configure an API key in the Viewer dashboard.

Creating an API Key

After logging in, navigate to the sidebar and go to the API Config section
Click the Create API Key button
Configure the following values:
- Description: A human-readable description to identify the key in the dashboard
- Study scope: Choose between Self or All
  - Self: For teleradiology groups with multiple integrating PACS sources. This ensures each PACS can only access, edit, and manage their own studies
  - All: For customers with a unified source of studies or integrators themselves (PACS companies looking to integrate Viewer into their platform)
- User access: Choose None, Read, or Write to determine if the API token can invite and manage users
- Express customer access: Explicitly for integrators (PACS companies) looking to serve Viewer as a product to all of their customers. Otherwise, leave as None since it won’t be needed
- Study data webhook endpoint: Your domain endpoint to generate study URLs for the viewer (leave blank if you are not going to use the viewer — can be edited later). Example: https://my-domain.com/api/generate-viewer-study-urls (see the Study Image Access webhook section below)
Once the API key is created, save it to your environment variables — you will not be able to view it again

Editing Webhook Endpoints

To edit webhook endpoints after creating an API key, click the Edit Endpoints button in the API config row for your key.

Viewing JWT Webhook Secret

To view the JWT secret for webhook integrations (it is auto-generated), click the View JWT Secret button in the API config row for your key. This secret can be viewed at any time.

Save this secret to your environment variables as AVARA_JWT_WEBHOOK_SECRET for use in webhook signature verification.

Creating Studies

The simplest integration pattern is creating studies programmatically using our SDKs. This allows you to automate study creation from your PACS, RIS, or other systems. Studies can also be fully created and managed in the dashboard if desired.

TypeScript

import Avara from 'avara';

const avara = new Avara({
  apiKey: process.env.AVARA_API_KEY
});

const study = await avara.viewer.studies.create({
  studyUid: '1.3.6.1.4.1.543245.54356543',
  studyDescription: 'Coronary CT Angiogram',
  severity: 'normal',
});

Python

import os
from avara import Avara

client = Avara(
    api_key=os.environ.get("AVARA_API_KEY"),
)
study = client.viewer.studies.create(
    severity="normal",
    study_description="Brain MRI with Contrast",
    study_instance_uid="1.2.840.113619.2.55.3.604688119.868.1234567890.123",
)

Java

package com.avara.example;

import com.avara.client.AvaraClient;
import com.avara.client.okhttp.AvaraOkHttpClient;
import com.avara.models.viewer.studies.StudyCreateParams;
import com.avara.models.viewer.studies.StudyCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AvaraClient client = AvaraOkHttpClient.fromEnv();

        StudyCreateParams params = StudyCreateParams.builder()
            .severity(StudyCreateParams.Severity.NORMAL)
            .studyDescription("Brain MRI with Contrast")
            .studyInstanceUid("1.2.840.113619.2.55.3.604688119.868.1234567890.123")
            .build();
        StudyCreateResponse study = client.viewer().studies().create(params);
    }
}

Temporary Access Views

Temporary access views enable you to generate reroute URLs that provide secure, authenticated access to Viewer without requiring users to log in to the Avara Viewer dashboard. This feature is designed for advanced PACS company users desiring a fully embedded experience in their platform and is completely optional.

How It Works

The flow for temporary access views is straightforward:

Authenticated users request access: Users authenticated in your platform request access to view a study
Server authorization: Your servers authorize the request and generate a reroute URL using our SDK. The URL is based on the study ID
Client-side redirect: Serve the URL to the user and redirect them client-side to a new window where they get a secure connection to view the study without needing to log in to the Avara Viewer dashboard

TypeScript

import Avara from 'avara';

const client = new Avara({
  apiKey: process.env['AVARA_API_KEY'],
});

const response = await client.viewer.studies.rerouteURL({
  studyId: 'stu_1234567890abcdef1234567890abcdef',
});

Python

import os
from avara import Avara

client = Avara(
    api_key=os.environ.get("AVARA_API_KEY"),
)
response = client.viewer.studies.reroute_url(
    study_id="stu_1234567890abcdef1234567890abcdef",
)

Java

package com.avara.example;

import com.avara.client.AvaraClient;
import com.avara.client.okhttp.AvaraOkHttpClient;
import com.avara.models.viewer.studies.StudyRerouteUrlParams;
import com.avara.models.viewer.studies.StudyRerouteUrlResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AvaraClient client = AvaraOkHttpClient.fromEnv();

        StudyRerouteUrlParams params = StudyRerouteUrlParams.builder()
            .studyId("stu_1234567890abcdef1234567890abcdef")
            .build();
        StudyRerouteUrlResponse response = client.viewer().studies().rerouteUrl(params);
    }
}

Webhooks

Viewer uses webhooks to integrate with your systems for study image access. Webhooks allow Avara to request data from your systems.

Webhook Security

All webhook requests from Avara include security headers that you must verify to ensure the request is authentic. Avara signs each webhook request using a JWT secret that you configure in your API key settings.

Verification Headers

Avara sends the following headers with each webhook request:

X-Avara-Signature: HMAC-SHA256 signature of the request payload
X-Avara-Timestamp: Unix timestamp (milliseconds) when the request was signed

You must verify the webhook signature using your AVARA_JWT_WEBHOOK_SECRET environment variable before processing any webhook event. The signature is computed as:

signature = HMAC-SHA256(secret, timestamp + payload)

TypeScript

import crypto from 'crypto';
import express, { Request, Response } from 'express';

const app = express();
app.use(express.json());

function verifyWebhookSignature(req: Request): boolean {
  const secret = process.env.AVARA_JWT_WEBHOOK_SECRET;
  if (!secret) {
    throw new Error('AVARA_JWT_WEBHOOK_SECRET not configured');
  }

  const signature = req.headers['x-avara-signature'] as string;
  const timestamp = req.headers['x-avara-timestamp'] as string;

  if (!signature || !timestamp) {
    return false;
  }

  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/avara', async (req: Request, res: Response) => {
  if (!verifyWebhookSignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
});

Python

import os
import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_webhook_signature(req) -> bool:
    secret = os.environ.get('AVARA_JWT_WEBHOOK_SECRET')
    if not secret:
        raise ValueError('AVARA_JWT_WEBHOOK_SECRET not configured')

    signature = req.headers.get('X-Avara-Signature')
    timestamp = req.headers.get('X-Avara-Timestamp')

    if not signature or not timestamp:
        return False

    payload = req.get_data(as_text=True)
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        (timestamp + payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

@app.route('/webhooks/avara', methods=['POST'])
def handle_webhook():
    if not verify_webhook_signature(request):
        return jsonify({'error': 'Invalid signature'}), 401

    # Process webhook...
    return jsonify({'success': True}), 200

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import javax.servlet.http.HttpServletRequest;
import com.fasterxml.jackson.databind.ObjectMapper;

@RestController
@RequestMapping("/webhooks")
public class WebhookController {

    private static final String HMAC_SHA256 = "HmacSHA256";
    private final ObjectMapper objectMapper = new ObjectMapper();

    private boolean verifyWebhookSignature(HttpServletRequest request, Object body) {
        String secret = System.getenv("AVARA_JWT_WEBHOOK_SECRET");
        if (secret == null) {
            throw new IllegalStateException("AVARA_JWT_WEBHOOK_SECRET not configured");
        }

        String signature = request.getHeader("X-Avara-Signature");
        String timestamp = request.getHeader("X-Avara-Timestamp");

        if (signature == null || timestamp == null) {
            return false;
        }

        try {
            String payload = objectMapper.writeValueAsString(body);

            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                secret.getBytes(StandardCharsets.UTF_8),
                HMAC_SHA256
            );
            mac.init(secretKeySpec);

            String message = timestamp + payload;
            byte[] hashBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
            String expectedSignature = bytesToHex(hashBytes);

            return MessageDigest.isEqual(
                signature.getBytes(StandardCharsets.UTF_8),
                expectedSignature.getBytes(StandardCharsets.UTF_8)
            );
        } catch (Exception e) {
            throw new RuntimeException("Failed to verify signature", e);
        }
    }

    private String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }

    @PostMapping("/avara")
    public ResponseEntity<?> handleWebhook(
        @RequestBody Object body,
        HttpServletRequest request
    ) {
        if (!verifyWebhookSignature(request, body)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body("Invalid signature");
        }

        // Process webhook...
        return ResponseEntity.ok().build();
    }
}

Study Image Access

The study.access_requested webhook is sent when Avara needs presigned URLs for DICOM images. This is a synchronous webhook — you must respond with the URLs within the request timeout. This webhook is sent before a study can be viewed in the Avara interface.

When Avara needs to access study images, it sends a POST request to your webhook endpoint. Your endpoint must respond with presigned URLs for the DICOM images.

TypeScript

Event Structure

interface StudyAccessRequestedWebhookEvent {
  id: string; // Format: whe_{32-hex-chars}
  type: "study.access_requested";
  data: {
    studyId: string; // Format: stu_{32-hex-chars}
    studyInstanceUid: string; // DICOM Study Instance UID
  };
}

Implementation

import express, { Request, Response } from 'express';

const app = express();
app.use(express.json());

// See Webhook Security section for verifyWebhookSignature implementation
app.post('/webhooks/avara', async (req: Request, res: Response) => {
  if (!verifyWebhookSignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = req.body as StudyAccessRequestedWebhookEvent;

  if (event.type === 'study.access_requested') {
    const { studyId, studyInstanceUid } = event.data;

    // This is your internal business logic
    const presignedUrls = await generatePresignedUrlsForStudy(studyInstanceUid);

    if (presignedUrls.length === 0) {
      return res.status(200).json({
        authorized: false,
        error: 'Study not found in PACS',
      });
    }

    res.status(200).json({
      authorized: true,
      urls: presignedUrls,
    });
  }
});

// This is your internal business logic
async function generatePresignedUrlsForStudy(
  studyInstanceUid: string
): Promise<string[]> {
  // Query your PACS/RIS system for the study
  // Generate presigned URLs for each DICOM image
  // Return a flat list of all image URLs
  return [
    'https://storage.example.com/dicom/image1.dcm?token=abc123',
    'https://storage.example.com/dicom/image2.dcm?token=def456',
  ];
}

Response Format

interface StudyAccessRequestedWebhookResponse {
  authorized: boolean;
  urls?: string[]; // Presigned URLs for DICOM images
  error?: string; // Error message if authorization failed
}

Python

Event Structure

from typing import TypedDict

class StudyAccessRequestedWebhookEvent(TypedDict):
    id: str  # Format: whe_{32-hex-chars}
    type: str  # "study.access_requested"
    data: dict  # Contains studyId and studyInstanceUid

Implementation

from flask import Flask, request, jsonify
from typing import List

app = Flask(__name__)

# See Webhook Security section for verify_webhook_signature implementation
@app.route('/webhooks/avara', methods=['POST'])
def handle_webhook():
    if not verify_webhook_signature(request):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json

    if event['type'] == 'study.access_requested':
        study_id = event['data']['studyId']
        study_instance_uid = event['data']['studyInstanceUid']

        # This is your internal business logic
        presigned_urls = generate_presigned_urls_for_study(study_instance_uid)

        if not presigned_urls:
            return jsonify({
                'authorized': False,
                'error': 'Study not found in PACS'
            }), 200

        return jsonify({
            'authorized': True,
            'urls': presigned_urls
        }), 200

# This is your internal business logic
def generate_presigned_urls_for_study(study_instance_uid: str) -> List[str]:
    # Query your PACS/RIS system for the study
    # Generate presigned URLs for each DICOM image
    # Return a flat list of all image URLs
    return [
        'https://storage.example.com/dicom/image1.dcm?token=abc123',
        'https://storage.example.com/dicom/image2.dcm?token=def456',
    ]

Response Format

from typing import TypedDict, Optional, List

class StudyAccessRequestedWebhookResponse(TypedDict, total=False):
    authorized: bool
    urls: Optional[List[str]]  # Presigned URLs for DICOM images
    error: Optional[str]  # Error message if authorization failed

Java

Event Structure

public class StudyAccessRequestedWebhookEvent {
    private String id; // Format: whe_{32-hex-chars}
    private String type; // "study.access_requested"
    private StudyAccessData data;

    public static class StudyAccessData {
        private String studyId; // Format: stu_{32-hex-chars}
        private String studyInstanceUid; // DICOM Study Instance UID
    }
}

Implementation

import org.springframework.web.bind.annotation.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import javax.servlet.http.HttpServletRequest;
import java.util.List;

@RestController
@RequestMapping("/webhooks")
public class WebhookController {

    // See Webhook Security section for verifyWebhookSignature implementation

    @PostMapping("/avara")
    public ResponseEntity<?> handleWebhook(
        @RequestBody StudyAccessRequestedWebhookEvent event,
        HttpServletRequest request
    ) {
        if (!verifyWebhookSignature(request, event)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body("Invalid signature");
        }

        if ("study.access_requested".equals(event.getType())) {
            String studyId = event.getData().getStudyId();
            String studyInstanceUid = event.getData().getStudyInstanceUid();

            // This is your internal business logic
            List<String> presignedUrls = generatePresignedUrlsForStudy(studyInstanceUid);

            if (presignedUrls.isEmpty()) {
                return ResponseEntity.ok(StudyAccessRequestedWebhookResponse.builder()
                    .authorized(false)
                    .error("Study not found in PACS")
                    .build());
            }

            return ResponseEntity.ok(StudyAccessRequestedWebhookResponse.builder()
                .authorized(true)
                .urls(presignedUrls)
                .build());
        }
        return ResponseEntity.ok().build();
    }

    // This is your internal business logic
    private List<String> generatePresignedUrlsForStudy(String studyInstanceUid) {
        // Query your PACS/RIS system for the study
        // Generate presigned URLs for each DICOM image
        // Return a flat list of all image URLs
        return List.of(
            "https://storage.example.com/dicom/image1.dcm?token=abc123",
            "https://storage.example.com/dicom/image2.dcm?token=def456"
        );
    }
}

Response Format

public class StudyAccessRequestedWebhookResponse {
    private boolean authorized;
    private List<String> urls; // Presigned URLs for DICOM images
    private String error; // Error message if authorization failed
}

API Reference

For complete API documentation, including all available operations, webhooks, and advanced features, see the API Reference.