Start a flow from an inbound API call or webhook from an external system. Configure the trigger start conditions without having to write or maintain custom code.

For example, you can create a flow that starts when a third-party IT ticket tracking system sends an inbound request to the instance. You can then parse the data from the inbound REST request into a complex data object and use the values to open an Incident on your instance.

Once you activate the flow, the endpoint that you created appears in the API explorer under the namespace you created. You can use this page to help define the webhook in your third-party system and to test your flow.

To learn more about flow triggers, see Flow Designer trigger types.

Note: Use the REST API Trigger to start flows from REST calls from external systems. To start a flow from a script or API call from the same instance, use a subflow, code snippet, or Flow Designer API. See API access to Flow Designer and Create code snippets for flows, sub-flows, and actions.

Available data pills

Depending on how you configure the endpoint, flow designers have access to these data pills from the trigger:

Path Parameters
An object containing path parameters in the inbound request.
Query Parameters
An object containing query parameters in the inbound request.
Request Headers
An object containing headers in the inbound request.
Request Body
Complex data object that defines the body structure of the inbound request. For more information on complex objects, see Complex data.

When setting up the trigger, define what the inbound data will look like. You can then use the associated data pills within the actions in your flow. When the system receives an inbound request that starts the flow, it uses the runtime values sent in the request.

Create a flow using the REST API trigger

Create a flow that starts when a third-party system sends a REST request to your instance.

Before you begin

Role required: flow_designer or admin.

This feature requires an Integration Hub subscription. For more information, see Legal schedules - IntegrationHub overview.

Procedure

  1. Open Flow Designer and create a flow.

    See Create a flow.

    Keep in mind that the scope of your flow is included in the REST endpoint you create.

  2. In the TRIGGER section, select the REST API - Asynchronous trigger.
  3. In the HTTP Method field, set the HTTP method for the endpoint.
    Options include:
    • POST
    • GET
    • DELETE
    • PUT
    • PATCH
  4. Create any path parameters required for the endpoint and add them to the relative path in the Path field.
    The relative path to the endpoint is in the format /api/<flow-application-scope>/<flow-name>/<path-parameters>.

    You can click Copy to copy the full path to the endpoint. Use this path when configuring the endpoint for the REST call in your third-party system.

    1. Create variables in the Path Parameters section.
    2. Drag the data pill that represents the path parameter into the empty input in the Path field.

      This field only accepts data pills from the Path Parameters section.

  5. Select Requires authentication to require authentication headers in the inbound REST request.
  6. If Requires authentication is selected, add the roles required to authorize the request in the Requires roles field.
  7. In the Body field under the Request Content section, create a complex data object that defines the body structure of the inbound request.

    For more information on building a complex object, see Complex data.

    Note: The Request Content section only appears when the HTTP Method is POST, PUT, or PATCH.

    This example body finds the Description field in an inbound payload that contains ticket information from a third-party ticket-tracking system.

  8. In the Headers field, define the headers to be sent in the inbound request.
    You can select Required to require that the inbound request include them.
  9. In the Query Parameters field, define the query parameters to be sent in the inbound request.
    You can select Required to require that the inbound request include them.
  10. Add actions to your flow that execute when the endpoint is called.

    You can use the data pills from the REST API trigger in your flow actions.

    This action creates an Incident record and maps the Description and Assignment Group fields from the incoming payload to the Incident.

  11. Test and activate the flow.
    For more information, see Test a flow and Activate a flow.

    Once activated, the endpoint displays in the REST API Explorer. You can use this page to further test your endpoint, or configure the request from your third-party system.

  12. Configure the REST request from your third-party system.
    For example, you can send this cURL request to trigger the flow defined in previous steps.
    curl "https:your-instance.servicenow.com/api/snc/create_incident_from_external_event/assignment_group/287ebd7da9fe198100f92cc8d1d2154e" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
fields: {
   description: \"Major outage with data loss\"
   }
}" \
--user 'username':'password'

Result

The flow executes and the REST request returns the execution ID.
{
  "result": {
    "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO"
  }
}

What to do next

Copy the execution ID in the result and navigate to the Executions tab in Flow Designer. You can filter by execution ID to locate the execution details and view the status of the execution.

To troubleshoot issues, you can debug the REST query or check the flow execution details. See Debug REST queries and Flow execution details.