Skip to main content

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 in subscriptions. 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:
  1. Automatic retry: Decoda retries the delivery a short number of times.
  2. Failure notification: An email is sent to the webhook’s notification_email after a delivery ultimately fails.
  3. 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

  1. Start your local server
  2. Expose it with ngrok: ngrok http 3000
  3. Use the ngrok URL when creating your webhook
  4. 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.