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.

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:

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

💬 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

Off-Exchange Example

{
  "transaction_id": "string",
  "application_id": "string",
  "event_type": "string",
  "policy_status": "string",
  "event_timestamp": "string",
  "external_id": "string",
  "policy_aor_npn": "string",
  "submitter_npn": "string",
  "npn_used_at_submission": "string",
  "members": [
    {
      "member_id": "string",
      "first_name": "string",
      "middle_name": "string",
      "last_name": "string",
      "date_of_birth": "string"
    }
  ],
  "policies": [
    {
      "policy_id": "string",
      "effective_date": "string",
      "expiration_date": "string",
      "status": "string",
      "plan_hios_id": "string",
      "gross_premium": 0.0,
      "members": [
        {
          "member_id": "string",
          "effective_date": "string",
          "removed_date": "string"
        }
      ],
      "agent_of_record": {
        "npn": "string",
        "first_name": "string",
        "last_name": "string",
        "state_license_number": "string",
        "email": "string"
      }
    }
  ]
}

On-Exchange Example

{
  "transaction_id": "string",
  "event_type": "string",
  "policy_status": "string",
  "event_timestamp": "string",
  "external_id": "string",
  "policy_aor_npn": "string",
  "submitter_npn": "string",
  "npn_used_at_submission": "string"
}

Step 4: Supported Events

Below are the possible following event_types and policy_status:

Event Type	Description
submission	An application submission from HealthSherpa to the Carrier or Exchange
sync	A delivered or received status change to an existing application/policy with a Carrier.

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