---
title: "Create new subscription"
method: POST
path: "/subscriptions"
tags: ["Subscriptions & Webhooks"]
---

# Create new subscription

`POST /subscriptions`

## Query parameters

- `skipWebhook` boolean

## Headers

- `x-organization-id` integer

## Request body

- union
  - object
    - `type` 'API_TOKEN_CREATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'API_TOKEN_REVOKED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'ASSET_STATUS_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `filters` object — Possible filters.
      - `oneOfAssetStatusTypes` string[] — Asset status types that will trigger the webhook
      - `oneOfCustomAssetStatusesIds` number[] — Custom status ids that will trigger the webhook
  - object
    - `type` 'CONNECTOR_TOKEN_REVOKED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'DATA_EXPORT_INITIATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'INVITE_LINK_ARCHIVED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'INVITE_LINK_CREATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'INVITE_LINK_UPDATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'METER_TRIGGER_STATE_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `filters` object — Possible filters.
      - `oneOfStates` string[] — States that will trigger the webhook.
  - object
    - `type` 'NEW_ASSET', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the Asset data
  - object
    - `type` 'NEW_CATEGORY_ON_WORK_ORDER', required — Type of event subscribed to
    - `url` string, required
    - `filters` object — Possible filters.
      - `oneOfCategories` union[] — At least one of those categories should be on the work order to trigger the webhook.
        - union
          - string — Category name
          - integer — Global ID of a category
  - object
    - `type` 'NEW_COMMENT_ON_WORK_ORDER', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'NEW_LOCATION', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'NEW_PART', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the Part data
  - object
    - `type` 'NEW_PURCHASE_ORDER', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the Purchase Order data
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
  - object
    - `type` 'NEW_WORK_REQUEST', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'NEW_SLASH_COMMAND', required — Type of event subscribed to
    - `url` string, required
    - `filters` object — Possible filters.
      - `command` string — Specify the required keyword to trigger the Webhook.
  - object
    - `type` 'NEW_VENDOR', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'NEW_WORK_ORDER', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the Work Order data
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
  - object
    - `type` 'PART_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the part data
      - `onlySerializeFilteredProperties` boolean — If true and serializeEntity is also set to true, only the filtered properties will be returned on update.
    - `filters` object — Possible filters.
      - `oneOfPartProperties` string[] — Properties that will trigger the webhook. <br>*If no properties are selected, the webhook will be triggered on every change
  - object
    - `type` 'PART_DELETE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the part data
  - object
    - `type` 'PART_QUANTITY_CHANGE', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'PART_TRANSFER', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'PURCHASE_ORDER_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the purchase order data
      - `onlySerializeFilteredProperties` boolean — If true and serializeEntity is also set to true, only the filtered properties will be returned on update.
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
    - `filters` object — Possible filters.
      - `oneOfPurchaseOrderProperties` string[] — Properties that will trigger the webhook. <br>*If no properties are selected, the webhook will be triggered on every changes
  - object
    - `type` 'PURCHASE_ORDER_STATUS_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializePurchaseOrder` boolean — If true, the webhook will receive the purchase order data
      - `omitSendToVendorPopup` boolean — If true, if the state change was done from the UI, the UI will not prompt the user to send the purchase order to the vendor. It will be assumed that the webhook took care of it.
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
    - `filters` object — Possible filters.
      - `oneOfStatuses` string[] — Statuses that will trigger the webhook
      - `vendors` number[] — Vendors id that will trigger the webhook
  - object
    - `type` 'ROLE_ARCHIVED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'ROLE_CREATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'ROLE_UPDATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'SSO_CONFIG_CHANGED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_ACTIVATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_INVITED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_LOGIN_FAILURE', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_LOGIN_SUCCESS', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_LOGOUT', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_PERMISSIONS_CHANGED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_REMOVED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_ROLE_CHANGED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'USER_SESSION_REVOKED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'WEBHOOK_ARCHIVED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'WEBHOOK_CREATED', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'WORK_ORDER_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the work order data
      - `onlySerializeFilteredProperties` boolean — If true and serializeEntity is also set to true, only the filtered properties will be returned on update.
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
    - `filters` object — Possible filters.
      - `oneOfProperties` string[] — Properties that will trigger the webhook. <br>*If no properties are selected, the webhook will be triggered on every changes
  - object
    - `type` 'WORK_ORDER_DELETE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the work order data
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
  - object
    - `type` 'WORK_ORDER_OVERDUE', required — Type of event subscribed to
    - `url` string, required
  - object
    - `type` 'WORK_ORDER_PART_STATUS_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the work order data
    - `filters` object — Possible filters.
      - `oneOfPartStatuses` string[] — Part status that will trigger the webhook. If empty or omitted, triggers for all part status changes.
  - object
    - `type` 'WORK_ORDER_STATUS_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `options` object — Possible options
      - `serializeEntity` boolean — If true, the webhook will receive the work order data
      - `includeOAuthTokensInPayload` boolean — If true, the webhook payload will include the OAuth tokens of the user whose action triggered the webhook. Warning: these tokens are sensitive and should only be included when the webhook is sent to a trusted source. Only available when OIDC login is enabled for the organization.
    - `filters` object — Possible filters.
      - `oneOfStatuses` string[] — Statuses that will trigger the webhook.<br> Note, that `"CANCELED"` and `"SKIPPED"` statuses are only available if this feature is enabled in your organization.
  - object
    - `type` 'WORK_REQUEST_STATUS_CHANGE', required — Type of event subscribed to
    - `url` string, required
    - `filters` object — Possible filters.
      - `oneOfStatuses` string[] — Statuses that will trigger the webhook.

## Response `201`

Successfully created subscription

- object
  - `id` integer, required — Global ID of the subscription
  - `status` 'VALID' | 'PENDING_APPROVAL', required — Validation status of the subscription. Contact support if your subscription returns PENDING_APPROVAL before using the subscription.
  - `secret` string — Secret to hash the Hmac signature

## Other responses

- `400` — OrganizationId was not provided
- `401` — Invalid token
- `403` — Failed to create the subscription

---

[API](https://skmtc.net/getmaintainx/apis/maintainx-api.md) · [All operations](https://skmtc.net/getmaintainx/apis/maintainx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getmaintainx/maintainx-api/revisions/ef9153fcac7c/schema)