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 OKor202 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 OKor202 Acceptedas 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.