Delivery Guarantees

Each notification is persisted until your system acknowledges receipt with a 2xx HTTP response. Messages are delivered in sequence, and failed deliveries are automatically retried with exponential backoff for a defined period. During this time, Health Gorilla retains the message in its queue.

If retries are exhausted, the Subscription is marked as failed, and deliveries pause until your organization restores endpoint availability and reactivates the subscription. No notification is silently dropped, and all delivery attempts are logged for traceability.

Idempotency and Deduplication

Because retries are part of reliable delivery, your system may occasionally receive the same notification more than once. Each notification includes a unique identifier that allows you to detect duplicates and ensure events are processed only once.

Your system should:

• Treat retries as expected, not as errors
• Use the unique event identifier to detect and skip duplicates
• Maintain idempotent processing logic to ensure consistent results

Shared Responsibility

Reliability depends on both sides of the delivery process. Health Gorilla maintains guaranteed delivery and retries, while your organization ensures prompt acknowledgment and resilient processing.

Your system should:

• Respond immediately with HTTP 200 OK when a notification is received
• Perform downstream processing asynchronously to avoid timeouts
• Maintain stable network availability and endpoint performance
• Rotate credentials before they expire to prevent interruptions

Monitoring and Maintenance

To maintain reliability in production environments, it is recommended that you:

• Monitor webhook latency, uptime, and response codes
• Alert your operations team when failure thresholds are reached
• Review delivery logs to verify subscription health
• Schedule periodic endpoint validation tests to confirm continued connectivity

Best Practices

To maximize reliability and minimize delivery failures, your organization should:

• Acknowledge quickly: Always return HTTP 200 OK immediately after receiving a notification. Perform additional processing asynchronously.
• Implement retry safety: Treat retries as expected. Use the notification identifier to deduplicate and avoid creating multiple records.
• Process asynchronously: Queue messages for downstream systems rather than coupling logic to the acknowledgment cycle.
• Monitor endpoints: Track webhook availability, latency, and error rates.
• Keep authentication current: Rotate endpoint secrets and tokens regularly to prevent failures due to expired or revoked credentials.

Reliability is ultimately a shared responsibility. Health Gorilla ensures messages are queued, retried, and visible, while your organization ensures that endpoints acknowledge quickly, handle duplicates safely, and remain available. Together, these practices protect against data loss and guarantee that subscription-driven workflows perform consistently.