# Webhooks API

Our Webhook APIs enable real-time communication between your system and ours, allowing you to receive timely updates as key events occur. To begin using our webhook functionality, there are a few setup steps that require coordination outside of the API itself.

### Overview

**HealthSherpa currently provides two webhook APIs: Submission Confirmation and Policy Status.** While both APIs share the same schema, they are triggered at different points in the member journey and can be subscribed to independently.

* **The Submission Confirmation** sends notifications when an enrollment application is submitted through HealthSherpa.
* **The Policy Status** sends notifications when a policy is effectuated, cancelled (i.e., never took effect) or terminated (i.e., ended after being in force).

The availability and accuracy of these updates depend on our connectivity with the Carrier, which is documented in [Supported Carriers](/integration-guide/supported-carriers.md).

Webhook delivery is not enabled by default. To ensure secure and accurate integration, we require some one-time configuration on our end before your system can start receiving webhook events.

This guide outlines:

* What you need to provide us
* How we will configure your webhook
* How to test and verify delivery
* The available webhook event types

### Step 1: Provide Your Webhook Configuration Details

To begin the setup process, please send the following information to your account manager or implementation specialist:

<table><thead><tr><th width="223.5">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Webhook URL</strong></td><td>The HTTPS endpoint on your server that will receive webhook POST requests</td></tr><tr><td><strong>Desired Authentication</strong></td><td>We support a variety of authentication methods. Provide any authentication credentials HealthSherpa will need for your selection.</td></tr><tr><td><strong>Exchange</strong></td><td>Whether you want to be notified of applications that are on-exchange, off-exchange, or both. </td></tr><tr><td><strong>Webhooks</strong></td><td>Whether you want to subscribe to the Submission Confirmation API, Policy Status API, or both.</td></tr><tr><td><strong>Environment</strong></td><td>Indicate whether it's for sandbox or production.</td></tr></tbody></table>

> 💬 Your onboarding contact will provide a form for you to fill out this information and return.

### Step 2: We Set Up the Webhook

Once we receive your details, we will:

* Register your endpoint in our system
* Enable webhook delivery for your account

We will notify you once your webhook is live in staging for testing.

### Step 3: Verify Webhook Delivery

To ensure successful delivery and security, all webhook requests:

* Are sent via **HTTPS POST**
* Contain the Headers consistent with the Authentication approach required by your system.
* Include a `Content-Type: application/json` header

{% code title="Off-Exchange Example" %}

```json
{
  "transaction_id": 123456789,
  "application_id": "HSA000000000",
  "policy_status": "effectuated",
  "event_type": "sync",
  "event_timestamp": "07/01/2025",
  "external_id": "f7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2",
  "policy_aor_npn": "1234567890",
  "submitter_npn": "17169718",
  "npn_used_at_submission": "17169718",
  "issuer_hios_id": "12345",
  "members": [
    {
      "member_id": "HSM000000000",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "05/10/1980"
    }
  ],
  "policies": [
    {
      "policy_id": "HSP000000000",
      "effective_date": "08/01/2025",
      "expiration_date": "12/31/2025",
      "status": "effectuated",
      "plan_hios_id": "12345LA0123456",
      "gross_premium": 750.25,
      "members": [
        {
          "member_id": "HSM000000000",
          "effective_date": "08/01/2025",
          "removed_date": null
        }
      ],
      "agent_of_record": {
        "npn": "1234567890",
        "first_name": "Tom",
        "last_name": "Doe",
        "state_license_number": "GA123456",
        "email": "tom.doe@healthsherpa.com"
      },
      "payment": {
        "payment_status": "paid",
        "payment_status_updated_date": "06/15/2025",
        "grace_period_start_date": "06/10/2025",
        "paid_through_date": "07/31/2025",
        "past_due_member_responsibility_balance_due": "0.00",
        "current_member_responsibility_balance_due": "50.50",
        "autopay_indicator": true
      }
    }
  ]
}
```

{% endcode %}

{% code title="On-Exchange Example" %}

```json
{
  "transaction_id": 123456789,
  "policy_status": "effectuated",
  "event_type": "sync",
  "event_timestamp": "2023-06-15T14:30:00Z",
  "external_id": "a1b2c3d4e5f6g7h8i9j0",
  "policy_aor_npn": "12345678",
  "submitter_npn": "87654321",
  "npn_used_at_submission": "87654321",
  "payment": {
    "payment_status": "paid",
    "payment_status_updated_date": "06/15/2025",
    "grace_period_start_date": "06/10/2025",
    "paid_through_date": "07/31/2025",
    "past_due_member_responsibility_balance_due": "0.00",
    "current_member_responsibility_balance_due": "50.50",
    "autopay_indicator": true
  }
}
```

{% endcode %}

### Step 4: Supported Events

Below are the possible following event\_types and policy\_status:

<table><thead><tr><th width="136.5">Event Type</th><th>Description</th></tr></thead><tbody><tr><td><code>submission</code></td><td>An application submission from HealthSherpa to the Carrier or Exchange</td></tr><tr><td><code>sync</code></td><td>A delivered or received status change to an existing application/policy with a Carrier.</td></tr></tbody></table>

<table><thead><tr><th width="208.5">Policy Status</th><th>Description</th></tr></thead><tbody><tr><td><code>pending_effectuation</code></td><td>Coverage pending effectuation; awaiting carrier confirmation, which may include binder payment or account setup—even for $0 plans.</td></tr><tr><td><code>effectuated</code></td><td>Coverage is active and binder payment has been received.</td></tr><tr><td><code>cancelled</code></td><td>Policy never effectuated and was cancelled, typically due to non-payment.</td></tr><tr><td><code>terminated</code></td><td>Policy was active and later terminated by consumer, carrier, or plan year expiration.</td></tr><tr><td><code>unknown</code></td><td>Enrollment status returned as unknown by CMS. On-ex only.</td></tr><tr><td><code>blank</code></td><td>Enrollment status unavailable due to system error or missing data. On-ex only.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ichra.healthsherpa.com/api-reference/webhooks-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.