Skip to content
/
Note Synchronization
Last updated

Note Synchronization

Learn how to integrate your practice management system with Askara to receive clinical notes automatically when they are generated from audio transcriptions.

Overview

When a healthcare professional records an audio consultation in Askara, the system transcribes it and generates a clinical note using AI. Your system can receive these notes automatically via webhook or retrieve them by polling the API.

Integration Flow

  1. Receive notification - Via webhook (push) or polling (pull)
  2. Retrieve note - Get note content and metadata via API
  3. Import to your system - Save the note in your database

Synchronization Methods

Webhooks provide real-time notifications when notes are generated. Askara sends an HTTP POST request to your endpoint.

Advantages:

  • Real-time synchronization
  • No polling overhead
  • Efficient resource usage

1. Register Your Webhook

Endpoint: POST /webhooks

-> API Reference: Create Webhook

{
  "url": "https://your-system.com/api/askara/webhook",
  "events": ["new_note"],
  "active": true
}

2. Receive Webhook Events

When a note is generated, Askara sends a POST request to your webhook URL.

Webhook Payload Structure:

{
  "events": [{
    "id": "note-uuid",
    "resource_type": "note",
    "action": "new_note",
    "metadata": {
      "note": {
        "uuid": "...",
        "type": "consultation_summary",
        "content": "Patient presents with...",
        "createdAt": "2026-02-24T10:30:00+00:00",
        "updatedAt": "2026-02-24T10:30:00+00:00",
        "patient": { "uuid": "...", "firstName": "...", "lastName": "..." }
      }
    },
    "resource_metadata": {
      "user_id": "...",
      "organization_id": "..."
    }
  }],
  "meta": {
    "webhook_id": "your-webhook-uuid"
  }
}

Important:

  • Respond with 200 OK within 5 seconds
  • Process the note asynchronously (don't block the response)
  • Use the note uuid for deduplication if the webhook is retried

3. Retrieve Full Note Details (Optional)

If you need additional data not included in the webhook payload (e.g., associated audio or user information), fetch the full note via API.

Endpoint: GET /notes/{uuid}

-> API Reference: Get Note

Option 2: Polling

If webhooks aren't feasible, poll periodically for new notes.

Endpoint: GET /notes

-> API Reference: List Notes

Useful query parameters:

  • patient=<patient-uuid> - Filter by patient
  • audio=<audio-uuid> - Filter by source audio
  • createdAt[after]=2026-02-17 - Filter by creation date
  • order[createdAt]=desc - Sort by newest first

Recommended polling interval: 30-60 seconds

Retry Behavior

If your webhook endpoint fails to respond (network error, timeout, non-2xx status code), Askara automatically retries delivery:

  • Retry 1: After 5 seconds
  • Retry 2: After 10 seconds
  • Retry 3: After 20 seconds
  • Max retries: 3 attempts

After 3 failed attempts, the webhook delivery is marked as failed and stored in the failure queue.

Required OAuth2 Scopes

To synchronize notes, your OAuth2 client must request this scope:

  • read:notes - Retrieve note information

-> OAuth2 Guide

Example Implementation

Node.js Webhook Handler

app.post('/api/askara/webhook', async (req, res) => {
  // Respond quickly to avoid timeout
  res.status(200).send('OK');

  const events = req.body.events;

  // Process asynchronously
  for (const event of events) {
    if (event.action === 'new_note') {
      const note = event.metadata.note;

      try {
        // Import note to your system
        await saveToSystem({
          uuid: note.uuid,
          content: note.content,
          patientUuid: note.patient?.uuid,
          createdAt: note.createdAt
        });

        console.log(`Successfully imported note ${note.uuid}`);
      } catch (error) {
        console.error(`Failed to import note ${note.uuid}:`, error);
      }
    }
  }
});

Best Practices

  1. Process asynchronously - Don't block webhook responses while processing
  2. Handle duplicates - Use note UUID to prevent duplicate imports
  3. Implement idempotency - Same note UUID should produce the same result
  4. Log failures - Include detailed error information for troubleshooting

Troubleshooting

Webhook Not Receiving Events

  • Verify your webhook URL is publicly accessible
  • Check that your endpoint responds with 200 OK within 5 seconds
  • Review webhook logs in Askara dashboard
  • Ensure your firewall allows Askara's IP addresses

Notes Not Appearing

  • Check OAuth2 token hasn't expired
  • Verify you have the read:notes scope
  • Confirm the audio transcription has completed before expecting a note

Next Steps

Previous page
Next page