Health Gorilla attempts to deliver every webhook event reliably, but network interruptions, application downtime, or endpoint issues can cause failures. This page explains how delivery errors are handled, how retries work, and how you can design your system to detect and recover from missed events.

What Counts as a Delivery Failure

A webhook delivery is considered to have failed if:

The HTTP response status is not 200 OK or 202 Accepted
The request times out
The server returns a 4xx or 5xx error code
The SSL certificate is invalid or expired
The endpoint is unreachable or DNS resolution fails

Retry Policy

If a webhook delivery fails, Health Gorilla will attempt retries using an exponential backoff strategy.

Retry Timing

Attempt	Approximate Delay
1st Retry	~5 seconds
2nd Retry	~30 seconds
3rd Retry	~2 minutes
Final Retry	~10 minutes

After the final retry attempt, the event is discarded and will not be redelivered.

Note: Persistent delivery failures may result in automatic deactivation of your subscription.

Best Practices for Error Resilience

To improve reliability and avoid lost data:

Respond quickly: Acknowledge successful delivery with 200 OK or 202 Accepted as soon as possible.
Use durable queuing: Store incoming events for asynchronous processing.
Log every event: Record delivery metadata (timestamp, resource ID, headers) for auditing and diagnostics.
Build in alerting: Notify your team if webhook deliveries start failing or backlogging.
Support re-ingestion: Make your processing idempotent so you can safely replay events.

Detecting Missed Events

Because webhooks are not guaranteed to be delivered, you should implement a reconciliation process to periodically compare:

The data received via webhook vs.
The latest data available via API query

Use the FHIR _lastUpdated parameter to request recently changed resources.