API Reference

Webhook Delivery & Security

Once a FHIR Subscription is active, Health Gorilla will send a webhook (HTTP POST) to the specified endpoint when a matching event occurs. This page outlines the format, delivery expectations, and security best practices for handling these notifications.

Delivery Format

Webhooks are delivered via HTTPS POST requests with a Content-Type of application/fhir+json. The request body will contain the full FHIR resource that triggered the event.

Example Request

POST /webhooks/hg HTTP/1.1
Host: yourapp.com
Content-Type: application/fhir+json
User-Agent: HealthGorilla-FHIR-Webhook
{
  "resourceType": "DocumentReference",
  "id": "12345",
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "34133-9",
        "display": "Summarization of episode note"
      }
    ]
  },
  "subject": {
    "reference": "Patient/abc-123"
  },
  "date": "2024-11-01T18:27:00Z"
}

HTTP Headers

Webhook requests will include these key headers:

HeaderDescription
Content-TypeAlways application/fhir+json
User-AgentIdentifies Health Gorilla delivery client
X-HealthGorilla-Event-Type(Optional) Event type or resource that triggered the webhook

Additional security headers may be added in the future.

HTTPS Requirement

All webhook endpoints must use HTTPS with valid TLS 1.2+ certificates.

  • Self-signed or invalid certificates will result in delivery failure.
  • Requests to http:// endpoints will be rejected.

Response Expectations

  • Your server must respond with HTTP 200 OK or HTTP 202 Accepted to confirm receipt.
  • Any other status code (e.g., 4xx, 5xx, timeouts) is treated as a failure and will trigger retry logic.
  • The webhook payload is not re-sent unless retry conditions are met (see below).

Retry Policy

If a webhook fails to deliver, Health Gorilla will retry delivery with exponential backoff.

AttemptDelay Before Retry
1st Retry~5 seconds
2nd Retry~30 seconds
3rd Retry~2 minutes
Final Retry~10 minutes
  • If all retries fail, the event is dropped.
  • Repeated failures may lead to automatic suspension of the subscription.

Idempotency

You should design your webhook receiver to be idempotent or, in other words, capable of safely processing the same event more than once.

Recommended strategies:

  • Track incoming resource.id + meta.lastUpdated to detect duplicates.
  • Store hashes or delivery timestamps to prevent double ingestion.