Webhooks

2026-02-01 · 4 min

Overview

Webhooks allow external systems to receive real-time notifications when events occur in Bio Ecko. Instead of polling the API for changes, your application receives HTTP POST callbacks at a URL you specify.

Configuring Webhooks

Set up webhooks under Admin > Settings > API > Webhooks:

1. Click Add Webhook.
2. Enter the endpoint URL where Bio Ecko should send events.
3. Select the events you want to subscribe to.
4. Optionally add a secret for signature verification.
5. Save. Bio Ecko sends a test ping to verify the endpoint is reachable.

You can configure multiple webhook endpoints for different event types or systems.

Available Events

Patient events: patient.created, patient.updated. Appointment events: appointment.booked, appointment.rescheduled, appointment.cancelled, appointment.checked_in. Clinical events: visit.started, visit.completed, prescription.created, lab_order.created, lab_result.ready. Billing events: invoice.created, invoice.paid, payment.received, refund.processed. Inventory events: stock.low, grn.completed, po.created. Admin events: user.created, user.role_changed.

Payload Format

Webhook payloads are JSON with a standard envelope:

{ "event": "lab_result.ready", "timestamp": "2026-03-15T14:30:00+05:30", "data": { "lab_order_id": "LO-2026-00456", "patient_id": "PAT-2026-00123", "test_name": "Complete Blood Count", "status": "verified" }, "webhook_id": "wh_abc123" }

The data object contains the relevant resource details for the event.

Security & Reliability

Webhook security:

• Signature Verification: Each webhook request includes an X-Bio-Ecko-Signature header. Compute HMAC-SHA256 of the request body using your webhook secret and compare.
• Retry Policy: Failed deliveries (non-2xx response or timeout) are retried 3 times with exponential backoff (1 min, 5 min, 30 min).
• Delivery Log: View delivery attempts, responses, and retry status under Webhooks > Delivery History.
• Idempotency: Each event has a unique webhook_id. Use it to deduplicate if your endpoint receives the same event twice.
• Timeout: Your endpoint must respond within 10 seconds. Use async processing for long-running tasks.

Testing

Test your webhook integration:

• Use the Test button next to each webhook to send a sample event.
• View the raw request and response in the delivery log.
• Use tools like webhook.site or ngrok for development testing.
• Monitor webhook health: Endpoints with consistently failed deliveries are auto-disabled after 100 consecutive failures with an admin notification.

Notes

Related topics