---
title: "Generate a step preview"
method: POST
path: "/v2/workflows/{workflowId}/step/{stepId}/preview"
tags: ["Workflows"]
---

# Generate a step preview

`POST /v2/workflows/{workflowId}/step/{stepId}/preview`

Generates a preview for a specific workflow step by its unique identifier **stepId**

## Path parameters

- `workflowId` string, required
- `stepId` string, required

## Headers

- `idempotency-key` string

## Request body

- GeneratePreviewRequestDto
  - `controlValues` object — Optional control values
  - `previewPayload` PreviewPayloadDto
    - `subscriber` SubscriberResponseDtoOptional
      - `_id` string — The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.
      - `firstName` string, nullable — The first name of the subscriber.
      - `lastName` string, nullable — The last name of the subscriber.
      - `email` string, nullable — The email address of the subscriber.
      - `phone` string, nullable — The phone number of the subscriber.
      - `avatar` string, nullable — The URL of the subscriber's avatar image.
      - `locale` string, nullable — The locale setting of the subscriber, indicating their preferred language or region.
      - `channels` ChannelSettingsDto[] — An array of channel settings associated with the subscriber.
        - `providerId` 'slack' | 'discord' | 'msteams' | 'webex-messaging' | 'mattermost' | 'ryver' | 'zulip' | 'grafana-on-call' | 'getstream' | 'rocket-chat' | 'whatsapp-business' | 'line' | 'chat-webhook' | 'novu-slack' | 'telegram' | 'sendblue' | 'novu-web-chat' | 'fcm' | 'apns' | 'expo' | 'one-signal' | 'pushpad' | 'push-webhook' | 'pusher-beams' | 'appio', required — The provider identifier for the credentials
        - `integrationIdentifier` string — The integration identifier
        - `credentials` ChannelCredentials, required
          - `webhookUrl` string — Webhook URL used by chat app integrations. The webhook should be obtained from the chat app provider.
          - `channel` string — Channel specification for Mattermost chat notifications.
          - `deviceTokens` string[] — Contains an array of the subscriber device tokens for a given provider. Used on Push integrations.
          - `alertUid` string — Alert UID for Grafana on-call webhook payload.
          - `title` string — Title to be used with Grafana on-call webhook.
          - `imageUrl` string — Image URL property for Grafana on-call webhook.
          - `state` string — State property for Grafana on-call webhook.
          - `externalUrl` string — Link to upstream details property for Grafana on-call webhook.
        - `_integrationId` string, required — The unique identifier of the integration associated with this channel.
      - `topics` string[] — An array of topics that the subscriber is subscribed to.
      - `isOnline` boolean, nullable — Indicates whether the subscriber is currently online.
      - `lastOnlineAt` string, nullable — The timestamp indicating when the subscriber was last online, in ISO 8601 format.
      - `__v` number — The version of the subscriber document.
      - `data` object, nullable — Additional custom data for the subscriber
      - `timezone` string, nullable — Timezone of the subscriber
    - `actor` SubscriberResponseDtoOptional
      - `_id` string — The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.
      - `firstName` string, nullable — The first name of the subscriber.
      - `lastName` string, nullable — The last name of the subscriber.
      - `email` string, nullable — The email address of the subscriber.
      - `phone` string, nullable — The phone number of the subscriber.
      - `avatar` string, nullable — The URL of the subscriber's avatar image.
      - `locale` string, nullable — The locale setting of the subscriber, indicating their preferred language or region.
      - `channels` ChannelSettingsDto[] — An array of channel settings associated with the subscriber.
        - `providerId` 'slack' | 'discord' | 'msteams' | 'webex-messaging' | 'mattermost' | 'ryver' | 'zulip' | 'grafana-on-call' | 'getstream' | 'rocket-chat' | 'whatsapp-business' | 'line' | 'chat-webhook' | 'novu-slack' | 'telegram' | 'sendblue' | 'novu-web-chat' | 'fcm' | 'apns' | 'expo' | 'one-signal' | 'pushpad' | 'push-webhook' | 'pusher-beams' | 'appio', required — The provider identifier for the credentials
        - `integrationIdentifier` string — The integration identifier
        - `credentials` ChannelCredentials, required
          - `webhookUrl` string — Webhook URL used by chat app integrations. The webhook should be obtained from the chat app provider.
          - `channel` string — Channel specification for Mattermost chat notifications.
          - `deviceTokens` string[] — Contains an array of the subscriber device tokens for a given provider. Used on Push integrations.
          - `alertUid` string — Alert UID for Grafana on-call webhook payload.
          - `title` string — Title to be used with Grafana on-call webhook.
          - `imageUrl` string — Image URL property for Grafana on-call webhook.
          - `state` string — State property for Grafana on-call webhook.
          - `externalUrl` string — Link to upstream details property for Grafana on-call webhook.
        - `_integrationId` string, required — The unique identifier of the integration associated with this channel.
      - `topics` string[] — An array of topics that the subscriber is subscribed to.
      - `isOnline` boolean, nullable — Indicates whether the subscriber is currently online.
      - `lastOnlineAt` string, nullable — The timestamp indicating when the subscriber was last online, in ISO 8601 format.
      - `__v` number — The version of the subscriber document.
      - `data` object, nullable — Additional custom data for the subscriber
      - `timezone` string, nullable — Timezone of the subscriber
    - `payload` object — Payload data
    - `steps` object — Steps data
    - `context` object
    - `env` object — Environment variables data

## Response `201`

Created

- GeneratePreviewResponseDto
  - `previewPayloadExample` PreviewPayloadDto, required
    - `subscriber` SubscriberResponseDtoOptional
      - `_id` string — The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.
      - `firstName` string, nullable — The first name of the subscriber.
      - `lastName` string, nullable — The last name of the subscriber.
      - `email` string, nullable — The email address of the subscriber.
      - `phone` string, nullable — The phone number of the subscriber.
      - `avatar` string, nullable — The URL of the subscriber's avatar image.
      - `locale` string, nullable — The locale setting of the subscriber, indicating their preferred language or region.
      - `channels` ChannelSettingsDto[] — An array of channel settings associated with the subscriber.
        - `providerId` 'slack' | 'discord' | 'msteams' | 'webex-messaging' | 'mattermost' | 'ryver' | 'zulip' | 'grafana-on-call' | 'getstream' | 'rocket-chat' | 'whatsapp-business' | 'line' | 'chat-webhook' | 'novu-slack' | 'telegram' | 'sendblue' | 'novu-web-chat' | 'fcm' | 'apns' | 'expo' | 'one-signal' | 'pushpad' | 'push-webhook' | 'pusher-beams' | 'appio', required — The provider identifier for the credentials
        - `integrationIdentifier` string — The integration identifier
        - `credentials` ChannelCredentials, required
          - `webhookUrl` string — Webhook URL used by chat app integrations. The webhook should be obtained from the chat app provider.
          - `channel` string — Channel specification for Mattermost chat notifications.
          - `deviceTokens` string[] — Contains an array of the subscriber device tokens for a given provider. Used on Push integrations.
          - `alertUid` string — Alert UID for Grafana on-call webhook payload.
          - `title` string — Title to be used with Grafana on-call webhook.
          - `imageUrl` string — Image URL property for Grafana on-call webhook.
          - `state` string — State property for Grafana on-call webhook.
          - `externalUrl` string — Link to upstream details property for Grafana on-call webhook.
        - `_integrationId` string, required — The unique identifier of the integration associated with this channel.
      - `topics` string[] — An array of topics that the subscriber is subscribed to.
      - `isOnline` boolean, nullable — Indicates whether the subscriber is currently online.
      - `lastOnlineAt` string, nullable — The timestamp indicating when the subscriber was last online, in ISO 8601 format.
      - `__v` number — The version of the subscriber document.
      - `data` object, nullable — Additional custom data for the subscriber
      - `timezone` string, nullable — Timezone of the subscriber
    - `actor` SubscriberResponseDtoOptional
      - `_id` string — The internal ID generated by Novu for your subscriber. This ID does not match the `subscriberId` used in your queries. Refer to `subscriberId` for that identifier.
      - `firstName` string, nullable — The first name of the subscriber.
      - `lastName` string, nullable — The last name of the subscriber.
      - `email` string, nullable — The email address of the subscriber.
      - `phone` string, nullable — The phone number of the subscriber.
      - `avatar` string, nullable — The URL of the subscriber's avatar image.
      - `locale` string, nullable — The locale setting of the subscriber, indicating their preferred language or region.
      - `channels` ChannelSettingsDto[] — An array of channel settings associated with the subscriber.
        - `providerId` 'slack' | 'discord' | 'msteams' | 'webex-messaging' | 'mattermost' | 'ryver' | 'zulip' | 'grafana-on-call' | 'getstream' | 'rocket-chat' | 'whatsapp-business' | 'line' | 'chat-webhook' | 'novu-slack' | 'telegram' | 'sendblue' | 'novu-web-chat' | 'fcm' | 'apns' | 'expo' | 'one-signal' | 'pushpad' | 'push-webhook' | 'pusher-beams' | 'appio', required — The provider identifier for the credentials
        - `integrationIdentifier` string — The integration identifier
        - `credentials` ChannelCredentials, required
          - `webhookUrl` string — Webhook URL used by chat app integrations. The webhook should be obtained from the chat app provider.
          - `channel` string — Channel specification for Mattermost chat notifications.
          - `deviceTokens` string[] — Contains an array of the subscriber device tokens for a given provider. Used on Push integrations.
          - `alertUid` string — Alert UID for Grafana on-call webhook payload.
          - `title` string — Title to be used with Grafana on-call webhook.
          - `imageUrl` string — Image URL property for Grafana on-call webhook.
          - `state` string — State property for Grafana on-call webhook.
          - `externalUrl` string — Link to upstream details property for Grafana on-call webhook.
        - `_integrationId` string, required — The unique identifier of the integration associated with this channel.
      - `topics` string[] — An array of topics that the subscriber is subscribed to.
      - `isOnline` boolean, nullable — Indicates whether the subscriber is currently online.
      - `lastOnlineAt` string, nullable — The timestamp indicating when the subscriber was last online, in ISO 8601 format.
      - `__v` number — The version of the subscriber document.
      - `data` object, nullable — Additional custom data for the subscriber
      - `timezone` string, nullable — Timezone of the subscriber
    - `payload` object — Payload data
    - `steps` object — Steps data
    - `context` object
    - `env` object — Environment variables data
  - `schema` object, nullable — The payload schema that was used to generate the preview payload example
  - `novuSignature` string — Sample novu-signature header value for HTTP request steps
  - `result` union, required — Preview result
    - object
    - object
      - `type` 'email'
      - `preview` EmailRenderOutput
        - `subject` string, required — Subject of the email
        - `body` string, required — Body of the email
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'email'
      - `preview` EmailRenderOutput
        - `subject` string, required — Subject of the email
        - `body` string, required — Body of the email
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'in_app'
      - `preview` InAppRenderOutput
        - `subject` string — Subject of the in-app notification
        - `body` string, required — Body of the in-app notification
        - `avatar` string — Avatar for the in-app notification
        - `primaryAction` ActionDto
          - `label` string — Label for the action button.
          - `redirect` RedirectDto
            - `url` string, required — URL to redirect to
            - `target` '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop' — Target attribute for the redirect link
        - `secondaryAction` ActionDto
          - `label` string — Label for the action button.
          - `redirect` RedirectDto
            - `url` string, required — URL to redirect to
            - `target` '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop' — Target attribute for the redirect link
        - `data` object — Additional data
        - `redirect` RedirectDto
          - `url` string, required — URL to redirect to
          - `target` '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop' — Target attribute for the redirect link
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'sms'
      - `preview` SmsRenderOutput
        - `body` string, required — Body of the SMS message
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'push'
      - `preview` PushRenderOutput
        - `subject` string, required — Subject of the push notification
        - `body` string, required — Body of the push notification
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'chat'
      - `preview` ChatRenderOutput
        - `body` string — Body of the chat message. Mutually exclusive with `card`.
        - `card` object — Rich Chat: compiled provider-agnostic card DSL. Mutually exclusive with `body`.
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'tool'
      - `preview` object
      - `error` PreviewErrorDto
        - `title` string, required — Short error title
        - `message` string, required — Detailed error message
        - `hint` string, required — Actionable hint for the user
    - object
      - `type` 'delay'
      - `preview` DigestRegularOutput
        - `amount` number, required — Amount of time units
        - `unit` 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months', required — Time unit
        - `digestKey` string — Optional digest key
        - `lookBackWindow` object — Look back window configuration
    - object
      - `type` 'digest'
      - `preview` DigestRegularOutput
        - `amount` number, required — Amount of time units
        - `unit` 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months', required — Time unit
        - `digestKey` string — Optional digest key
        - `lookBackWindow` object — Look back window configuration

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `405` — Method Not Allowed
- `409` — Conflict
- `413` — Payload Too Large
- `414` — URI Too Long
- `415` — Unsupported Media Type
- `422` — Unprocessable Entity
- `429` — The client has sent too many requests in a given amount of time.
- `500` — Internal Server Error
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

## Changes

- **2026-08-30** `24e82408dec7` — 2 breaking, 2 warning, 4 info
  - removed the enum value `novu-agent-chat` of the request property `previewPayload/allOf[#/components/schemas/PreviewPayloadDto]/actor/allOf[#/components/schemas/SubscriberResponseDtoOptional]/channels/items/providerId`
  - removed the enum value `novu-agent-chat` of the request property `previewPayload/allOf[#/components/schemas/PreviewPayloadDto]/subscriber/allOf[#/components/schemas/SubscriberResponseDtoOptional]/channels/items/providerId`
  - added the new `novu-web-chat` enum value to the `previewPayloadExample/allOf[#/components/schemas/PreviewPayloadDto]/actor/allOf[#/components/schemas/SubscriberResponseDtoOptional]/channels/items/providerId` response property for the response status `201`
  - added the new `novu-web-chat` enum value to the `previewPayloadExample/allOf[#/components/schemas/PreviewPayloadDto]/subscriber/allOf[#/components/schemas/SubscriberResponseDtoOptional]/channels/items/providerId` response property for the response status `201`
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/novu/apis/novu-api/changes/v2/workflows/:workflowId/step/:stepId/preview/post.md)

---

[API](https://skmtc.dev/novu/apis/novu-api.md) · [All operations](https://skmtc.dev/novu/apis/novu-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/novu/novu-api/revisions/24e82408dec7/schema)