# 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

### Option 1: Webhooks (Recommended)

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](/apis/askara-symfony/askara-api/webhook#create-webhook)


```json
{
  "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:**


```json
{
  "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](/apis/askara-symfony/askara-api/note#get-note)

### Option 2: Polling

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

**Endpoint:** `GET /notes`

[-> API Reference: List Notes](/apis/askara-symfony/askara-api/note#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](/guides/oauth2)

## Example Implementation

### Node.js Webhook Handler


```javascript
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

- **[API Reference](/apis/askara-symfony/askara-api)** - Explore all endpoints
- **[Document Synchronization](/guides/document-synchronization)** - Synchronize validated documents
- **[OAuth2 Authentication](/guides/oauth2)** - Secure your integration
- **[Rate Limiting](/guides/rate_limiting)** - Understand API limits