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

The following event types can be subscribed to:

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_COMPLETED

Fired when a payment successfully completes processing.

PAYMENT_FAILED

Fired when a payment 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

If your webhook endpoint returns a non-2xx status code or times out:
  1. Immediate retry: After 1 second
  2. Exponential backoff: Subsequent retries after 5s, 15s, 60s, 5min, 15min
  3. Maximum attempts: 6 attempts over ~30 minutes
  4. Failure notification: Email sent to notification_email after final failure

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.