<h2>REST API trigger</h2><br/><div style="overflow-x:auto"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta content="text/html; charset=UTF-8" /><meta name="copyright" content="(C) Copyright 2023" /><meta name="DC.rights.owner" content="(C) Copyright 2023" /><meta name="generator" content="DITA-OT" /><meta name="DC.type" content="concept" /><meta name="DC.title" content="REST API trigger" /><meta name="abstract" content="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." /><meta name="description" content="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." /><meta name="DC.relation" scheme="URI" content="../../../administer/integrationhub/concept/integrationhub.html" /><meta name="DC.relation" scheme="URI" content="../../../build/create-integrations-apps/concept/create-integrations-applications.html" /><meta name="DC.creator" content="ServiceNow" /><meta name="DC.date.created" content="2023-02-02" /><meta name="DC.date.modified" content="2023-02-02" /><meta name="DC.format" content="XHTML" /><meta name="DC.identifier" content="rest-trigger" /><link rel="stylesheet" type="text/css" href="../../../CSS/commonltr.css" /><title>REST API trigger</title></head><body> <div class="nested0" id="rest-trigger"> <h1 class="title topictitle1" id="ariaid-title1">REST API trigger</h1> <div class="body conbody"><p class="shortdesc"><span class="ph">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.</span></p> <div class="section" id="rest-trigger__section_sxx_crs_2nb"> <p class="p">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.</p> <p class="p">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.</p> <p class="p">To learn more about flow triggers, see <span class="xref"><span class="ph">Flow Designer</span> trigger types</span>.</p> <div class="p"><div class="note"><span class="notetitle">Note:</span> 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 <span class="ph">Flow Designer</span> API. See <span class="xref">API access to <span class="ph">Flow Designer</span></span> and <span class="xref">Create code snippets for flows, sub-flows, and actions</span>.</div> </div> </div> <div class="section" id="rest-trigger__section_cfs_yqx_nnb"><h2 class="title sectiontitle">Available data pills</h2> <p class="p">Depending on how you configure the endpoint, flow designers have access to these data pills from the trigger:</p> <div class="p"><dl class="dl"><dt class="dt dlterm">Path Parameters</dt><dd class="dd">An object containing path parameters in the inbound request.</dd><dt class="dt dlterm">Query Parameters</dt><dd class="dd">An object containing query parameters in the inbound request.</dd><dt class="dt dlterm">Request Headers</dt><dd class="dd">An object containing headers in the inbound request.</dd><dt class="dt dlterm">Request Body</dt><dd class="dd">Complex data object that defines the body structure of the inbound request. For more information on complex objects, see <span class="xref"></span>.</dd></dl> </div> <p class="p">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.</p> </div> </div> <div class="related-links"> <div class="familylinks"> <div class="parentlink"><strong>Parent Topic:</strong> <a class="link" href="../../../administer/integrationhub/concept/integrationhub.html" title="Automate integration tasks using ServiceNow components for Flow Designer, or develop custom integrations. A separate subscription is required.">Integration Hub</a></div> </div> </div><div class="topic task nested1" id="create-rest-trigger"> <h2 class="title topictitle2" id="ariaid-title2">Create a flow using the REST API trigger</h2> <div class="body taskbody"><p class="shortdesc">Create a flow that starts when a third-party system sends a REST request to your instance.</p> <div class="section prereq p"> <p class="p">Role required: flow_designer or admin.</p> <div class="p"><div class="note"><span class="notetitle">Note:</span> This feature requires an <span class="ph">Integration Hub</span> Enterprise subscription. For more information, see <a class="xref" href="../../flow-designer/concept/request-ih-overview.html" title="ServiceNow Integration Hub lets you build reusable integrations with third-party systems and call them from anywhere in the Now Platform. For example, you can request Integration Hub to call external systems using integration APIs from the Action Designer Script step, run the Script step on the ServiceNow MID Server, and activate protocol steps like REST, SOAP, and PowerShell.">Request Integration Hub</a>.</div> </div> </div> <ol class="ol steps"><li class="li step stepexpand"> <span class="ph cmd">Open <span class="ph">Flow Designer</span> and create a flow. See <span class="xref">Create a flow</span>.</span> <div class="itemgroup info">Keep in mind that the scope of your flow is included in the REST endpoint you create.</div> </li><li class="li step stepexpand"> <span class="ph cmd">In the <span class="ph uicontrol">TRIGGER</span> section, select the <span class="ph uicontrol">REST API - Asynchronous</span> trigger.</span> </li><li class="li step stepexpand"> <span class="ph cmd">In the <span class="ph uicontrol">HTTP Method</span> field, set the HTTP method for the endpoint.</span> <div class="itemgroup info">Options include:<ul class="ul" id="create-rest-trigger__ul_dmw_x35_jnb"><li class="li">POST</li><li class="li">GET</li><li class="li">DELETE</li><li class="li">PUT</li><li class="li">PATCH</li></ul> </div> </li><li class="li step stepexpand"> <span class="ph cmd">Create any path parameters required for the endpoint and add them to the relative path in the <span class="ph uicontrol">Path</span> field.</span> <div class="itemgroup info">The relative path to the endpoint is in the format <code class="ph codeph">/api/<flow-application-scope>/<flow-name>/<path-parameters></code>. <p class="p">You can click <span class="ph uicontrol">Copy</span> to copy the full path to the endpoint. Use this path when configuring the endpoint for the REST call in your third-party system.</p> <p class="p"><img class="image" id="create-rest-trigger__image_ef2_sdz_jnb" src="../images/rest-trigger-path.png" alt="" /></p> </div> <ol type="a" class="ol substeps" id="create-rest-trigger__substeps_fqn_bj5_jnb"><li class="li substep substepexpand"> <span class="ph cmd">Create variables in the <span class="ph uicontrol">Path Parameters</span> section.</span> </li><li class="li substep substepexpand"> <span class="ph cmd">Drag the data pill that represents the path parameter into the empty input in the <span class="ph uicontrol">Path</span> field. This field only accepts data pills from the <span class="ph uicontrol">Path Parameters</span> section.</span> <div class="itemgroup info"> <img class="image" id="create-rest-trigger__image_z4q_ptx_nnb" src="../images/rest-trigger-path-arrows.png" alt="" /> </div> </li></ol> </li><li class="li step stepexpand"> <span class="ph cmd">Select <span class="ph uicontrol">Requires authentication</span> to require authentication headers in the inbound REST request.</span> </li><li class="li step stepexpand"> <span class="ph cmd">If <span class="ph uicontrol">Requires authentication</span> is selected, add the roles required to authorize the request in the <span class="ph uicontrol">Requires roles</span> field.</span> </li><li class="li step stepexpand"> <span class="ph cmd">In the <span class="ph uicontrol">Body</span> field under the <span class="ph uicontrol">Request Content</span> section, create a complex data object that defines the body structure of the inbound request. For more information on building a complex object, see <span class="xref">Complex data</span>.</span> <div class="itemgroup info"> <div class="p"><div class="note"><span class="notetitle">Note:</span> The <span class="ph uicontrol">Request Content</span> section only appears when the <span class="ph uicontrol">HTTP Method</span> is POST, PUT, or PATCH.</div> </div> <p class="p">This example body finds the Description field in an inbound payload that contains ticket information from a third-party ticket-tracking system.</p> <p class="p"><img class="image" id="create-rest-trigger__image_opl_1gz_jnb" src="../images/rest-trigger-body.png" alt="" /></p> </div> </li><li class="li step stepexpand"> <span class="ph cmd">In the <span class="ph uicontrol">Headers</span> field, define the headers to be sent in the inbound request. Select <span class="ph uicontrol">Required</span> to require that the inbound request include them.</span> </li><li class="li step stepexpand"> <span class="ph cmd">In the <span class="ph uicontrol">Query Parameters</span> field, define the query parameters to be sent in the inbound request. Select <span class="ph uicontrol">Required</span> to require that the inbound request include them.</span> </li><li class="li step stepexpand"> <span class="ph cmd">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.</span> <div class="itemgroup info"> <p class="p">This action creates an Incident record and maps the Description and Assignment Group fields from the incoming payload to the Incident.</p> <p class="p"><img class="image" id="create-rest-trigger__image_jvt_23z_jnb" src="../images/rest-trigger-action.png" alt="" /></p> </div> </li><li class="li step stepexpand"> <span class="ph cmd">Test and activate the flow. For more information, see <span class="xref">Test a flow</span> and <span class="xref">Activate a flow</span>.</span> <div class="itemgroup info">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.<p class="p"><img class="image" id="create-rest-trigger__image_cqg_nmz_jnb" width="800" src="../images/rest-trigger-api-explorer.png" alt="" /></p> </div> </li><li class="li step stepexpand"> <span class="ph cmd">Configure the REST request from your third-party system.</span> <div class="itemgroup stepxmp">For example, you can send this cURL request to trigger the flow defined in previous steps.<pre class="pre codeblock"><code>curl "https:your-instance.servicenow.com/api/now/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'</code></pre> </div> </li></ol> <div class="section result" id="create-rest-trigger__result_dlr_b45_jnb">The flow executes and the REST request returns the execution ID.<pre class="pre codeblock"><code>{ "result": { "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO" } }</code></pre> </div> <div class="section postreq" id="create-rest-trigger__postreq_qcq_xcz_nnb"> <p class="p">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.</p> <p class="p"><img class="image" id="create-rest-trigger__image_g12_f2z_nnb" src="../images/rest-trigger-execution.png" alt="" /></p> <p class="p">To troubleshoot issues, you can debug the REST query or check the flow execution details. See <span class="xref">Debug REST queries</span> and <span class="xref">Flow execution details</span>.</p> </div> </div> </div> </div> </body></html></div>