Webhook Events Reference
Webhooks allow you to receive real-time notifications about events in your Decoda Health account. This guide documents all available event types and their payload structures.Available Event Types
A webhook subscribes to one or more event types. When you create or update a webhook, pass the event names you care about insubscriptions. A delivery is sent whenever a subscribed event
occurs in your account — so an event only fires if you use the corresponding feature (e.g. you
won’t receive FAX_RECEIVED deliveries if faxing is unused).
Real-time, UI-only signals (live typing indicators, presence, screen-pops, cache-refresh
pings, and similar) are not deliverable over webhooks and cannot be subscribed to — they
exist only to drive the in-app experience. Subscribing to an event type that is not
deliverable is rejected with a
422.Patients
Scheduling
Appointment checklist
Billing & Payments
Deposits & Chargebacks
Communications
Forms, Notes & Tasks
Growth
Inventory
Event Payload Structure
All webhook events follow this structure:Common Fields
- id: Unique identifier for the webhook event
- type: The event type (see table above)
- data: Event-specific payload (varies by event type)
- createdDate: ISO 8601 timestamp when the event occurred
- alertId: Associated alert ID for tracking
Event-Specific Payloads
PAYMENT_CREATED
Fired when a payment is initiated (before processing completes).PAYMENT_SUCCEEDED
Fired when a payment successfully completes processing.PLANNED_PAYMENT_FAILED
Fired when a scheduled payment-plan installment fails to process.CHARGE_CREATED
Fired when a new charge/bill is created.ADJUSTMENT_CREATED
Fired when an adjustment (discount, write-off, etc.) is applied to a charge.REFUND_CREATED
Fired when a refund is processed.PATIENT_CREATED
Fired when a new patient record is created.PATIENT_UPDATED
Fired when a patient record is updated.Webhook Delivery
Delivery Guarantees
- At-least-once delivery: Events may be delivered multiple times
- Ordering: Events are delivered in order, but network issues may cause out-of-order delivery
- Idempotency: Always check event IDs to avoid processing duplicates
Retry Logic
Each delivery uses a 5-second timeout. If your endpoint returns a non-2xx status code or times out:- Automatic retry: Decoda retries the delivery a short number of times.
- Failure notification: An email is sent to the webhook’s
notification_emailafter a delivery ultimately fails. - Manual re-send: You can re-trigger any recorded delivery from the Send Webhook Event endpoint.
Best Practices
Idempotency
Always check event IDs to prevent duplicate processing. Store processed event IDs in your database.
Quick Response
Respond quickly (within 5 seconds) to avoid timeouts. Process events asynchronously if needed.
Error Handling
Return proper HTTP status codes. 2xx = success, anything else triggers retries.
Signature Verification
Always verify webhook signatures to ensure events are from Decoda Health.
Example Webhook Handler
Here’s a complete example of handling webhooks:Testing Webhooks
Using ngrok for Local Development
- Start your local server
- Expose it with ngrok:
ngrok http 3000 - Use the ngrok URL when creating your webhook
- Test events will be delivered to your local server
Webhook Testing Endpoint
You can manually trigger webhook events using the Send Webhook Event endpoint for testing purposes.Related Documentation
- Webhook Setup Guide - Learn how to create and configure webhooks
- Webhook Security - Understand webhook signature verification
- API Reference: Webhooks - Complete webhook API documentation

