---
title: "Create webhook subscription (beta)"
method: POST
path: "/webhook_endpoints/{id}/webhook_subscriptions"
tags: ["Webhook Subscriptions"]
---

# Create webhook subscription (beta)

`POST /webhook_endpoints/{id}/webhook_subscriptions`

## Request

- Base URL: `https://nexhealth.info`
- URL: `https://nexhealth.info/webhook_endpoints/{id}/webhook_subscriptions`
- Auth: API key in header `Authorization`

> 🚧 Beta
>
> Send `Nex-Api-Version: v3.1.0` to use this endpoint. It is still changing, and access is limited to approved partner institutions. Contact NexHealth before you build on it.

> **Changed from v3.0.0:** Adds request field `version`; changes request fields `event`, `resource_type`; adds response `422`; adds response field `data.version`.

This endpoint creates a webhook subscription on the given webhook endpoint; the optional `version` param pins the subscription to a specific API version for payload delivery, defaulting to v3.1.0 when omitted, and returns 422 if the version is unknown or does not support the subscribed event.

## Path parameters

- `id` integer, required

## Query parameters

- `subdomain` string, required

## Headers

- `Nex-Api-Version` string, required

## Request body

- PostWebhookEndpointsIdWebhookSubscriptions: Create webhook subscription
  - `resource_type` 'Adjustment' | 'AdjustmentType' | 'Appointment' | 'Charge' | 'Claim' | 'Document' | 'FeeSchedule' | 'FormResponse' | 'FormSchema' | 'Insurance' | 'LocationDataReadiness' | 'MedicalHistory' | 'Message' | 'Onboarding' | 'Patient' | 'PatientInsuranceCoverage' | 'Payment' | 'PaymentType' | 'Procedure' | 'ProcedureCode' | 'Provider' | 'SyncStatus' | 'TreatmentPlan' | 'WorkingHour', required: The resource to subscribe to
  - `event` 'adjustment_created' | 'adjustment_updated' | 'adjustment_deleted' | 'adjustment_insertion' | 'adjustment_type_created' | 'adjustment_type_updated' | 'appointment_insertion' | 'appointment_created' | 'appointment_updated' | 'appointment_requested' | 'charge_created' | 'charge_updated' | 'charge_deleted' | 'claim_created' | 'claim_updated' | 'claim_deleted' | 'document_insertion' | 'fee_schedule_created' | 'fee_schedule_updated' | 'form_response_insertion' | 'form_schema_created' | 'form_schema_deleted' | 'insurance_plan_insertion' | 'insurance_coverage_insertion' | 'insurance_coverage_deleted' | 'location_data_ready' | 'medical_history_item_created' | 'medical_history_item_updated' | 'medical_history_patient_items_updated' | 'message_created' | 'message_updated' | 'onboarding_created' | 'onboarding_updated' | 'onboarding_availability_ready' | 'patient_created' | 'patient_updated' | 'patient_insertion' | 'patient_update' | 'patient_insurance_created' | 'patient_insurance_updated' | 'payment_created' | 'payment_updated' | 'payment_deleted' | 'payment_insertion' | 'payment_type_created' | 'payment_type_updated' | 'procedure_created' | 'procedure_updated' | 'procedure_code_created' | 'procedure_code_updated' | 'procedure_code_deleted' | 'provider_created' | 'provider_updated' | 'sync_status_read_change' | 'sync_status_write_change' | 'treatment_plan_created' | 'treatment_plan_updated' | 'treatment_plan_deleted' | 'working_hour_created' | 'working_hour_updated', required: A valid event type to listen to for the defined resource
  - `active` boolean
  - `version` string: API version to pin this subscription to. Defaults to the version this request is made against (v3.1.0) when omitted. Webhook payloads delivered to this subscription use that version's entity contract. v3.0.0 and v20240412 are two names for the same version — either value is accepted, and the subscription is recorded under the canonical name v20240412. Returns 422 for unknown versions and for versions that do not offer the subscribed event.

## Response `201`

Successful

- APIV31EntitiesWebhookSubscriptionResponse: API_V31_Entities_WebhookSubscription_Response model
  - `code` boolean: Indicates the success or failure of the request
  - `description` string: Additional context on the request to help with debugging.
  - `error` string[]: Any errors that occur during the execution of the request.
  - `data` APIV31EntitiesWebhookSubscription
    - `id` integer: Subscription ID
    - `webhook_endpoint_id` integer: Webhook Endpoint ID
    - `institution_id` integer, nullable: Institution ID. Null for subscriptions to resources not owned by an institution (currently: Onboarding)
    - `resource_type` string: Resource type
    - `event` string: Event type
    - `active` boolean: True if subscription is active
    - `created_at` string, date-time: Subscription create date in UTC
    - `updated_at` string, date-time: Subscription update date in UTC
    - `version` string: API version this subscription is pinned to. Webhook payloads delivered to this subscription use the entity contract registered for this version. See the version lifecycle docs for what changes happen within a version label vs across versions.
  - `count` integer: Number of total objects, in case of collection.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta.md) - [All operations](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/nexhealth/apis/nexhealth-api-v3-1-0-beta/revisions/93cb4af790a5?raw)