CONNECTOR SDK REFERENCE5 of 10

Event Handlers

Receive and process events from external systems in real time.

OverviewSubscribePayloadsProcessingAcknowledgementRetries & DLQOrderingBest Practices

How it works

1. Subscribe

Declare event types

2. Receive

Mediloop delivers events

3. Validate

Verify signature & scopes

4. Process

Transform and handle

5. Acknowledge

Return 2xx

typescriptCopy

export async function subscribe(ctx) {
 return { events: ['patient.created','medication.updated','observation.resulted'] };
}

Supported event types

patient.created / updated / deleted

encounter.created / updated / closed

medication.ordered / dispensed / cancelled

observation.resulted

document.added / updated

appointment.scheduled / cancelled

Event handling checklist

Validate event signature and expiry

Validate tenant and scopes

Check idempotency

Process within timeout

Acknowledge or return structured error

Example: onEvent handler

typescriptCopy

export async function onEvent(event: EventEnvelope, ctx) {
 if (!ctx.verifySignature(event)) throw new MediloopConnectorError('INVALID_SIGNATURE');
 const { type, id, occurredAt, data, correlationId } = event;
 if (await ctx.isDuplicate(id)) {
   ctx.logger.info('Duplicate event acknowledged',{id});
   return { status: 200 };
 }
 const mapped = await mapEventToMediloop(type, data, ctx);
 await ctx.emit(mapped);
 await ctx.markProcessed(id);
 ctx.logger.info('Event processed',{type,id,correlationId});
 return { status: 200 };
}

Event envelope (example)

jsonCopy

{
 "eventId":"evt_01H8Z...",
 "type":"patient.created",
 "occurredAt":"2026-08-31T10:15:30Z",
 "source":{"system":"acme-ehr","id":"SYS_123"},
 "tenantId":"tenant_123",
 "correlationId":"c_01H8Y...",
 "data":{...}
}

Acknowledge

200 OKprocessed successfully

202 Acceptedaccepted for async work

4xx/5xxwill be retried

Timeouts