Gatilho da REST API

Versão de lançamento: Zurich

Atualizado 31 de jul. de 2025

5 min. de leitura

Inicie um fluxo a partir de uma chamada de API de entrada ou webhook de um sistema externo. Configure as condições de início do gatilho sem precisar gravar ou manter código personalizado.

Por exemplo, você pode criar um fluxo que começa quando um sistema de acompanhamento de tíquete de TI DE terceiros envia uma solicitação de entrada para a instância. Em seguida, você pode analisar os dados da solicitação REST de entrada em um objeto de dados complexo e usar os valores para abrir um incidente em sua instância.

Depois que você ativa o fluxo, o endpoint que você criou aparece no explorador de API no namespace que você criou. Você pode usar esta página para ajudar a definir o webhook em seu sistema de terceiros e para testar seu fluxo.

Para saber mais sobre gatilhos de fluxo, consulte Workflow Studio tipos de gatilho.

Nota:

Use o gatilho da REST API para iniciar fluxos de chamadas REST de sistemas externos. Para iniciar um fluxo de um script ou chamada de API da mesma instância, use um subfluxo, snippet de código ou Workflow Studio API. Confira Acesso de API para Workflow Studio e. Crie snippets de código para fluxos, subfluxos e ações .
A ServiceNow fez parceria com Boomi para entregar Boomi API Management, Uma plataforma baseada em nuvem que permite que os clientes descubram, gerenciem, protejam e monetizem suas APIs. Boomi Oferece suporte ao gerenciamento de APIs de ciclo de vida completo, incluindo governança, análise e segurança de APIs.

Boomi fornece documentação por seu próprio portal e clientes que solicitam suporte com Boomi API Management entrará em contato com Boomi suporte por meio de seus canais padrão.

Para começar, consulte Boomi API Management listagem no ServiceNow® Store, que inclui informações sobre direitos e plug-ins necessários, bem como um link para Boomi API Management documentação.

Cápsulas de dados disponíveis

Dependendo de como você configurar o endpoint, os designers de fluxo terão acesso a essas cápsulas de dados do gatilho:

Parâmetros de caminho: Um objeto que contém parâmetros de caminho na solicitação de entrada.
Parâmetros de Consulta: Um objeto que contém parâmetros de consulta na solicitação de entrada.
Solicitar Cabeçalhos: Um objeto que contém cabeçalhos na solicitação de entrada.
Corpo da Solicitação: Objeto de dados complexo que define a estrutura do corpo da solicitação de entrada. Para obter mais informações sobre objetos complexos, consulte Complex data.

Ao configurar o gatilho, defina como serão os dados de entrada. Em seguida, você pode usar as cápsulas de dados associadas nas ações em seu fluxo. Quando o sistema recebe uma solicitação de entrada que inicia o fluxo, ele usa os valores de tempo de execução enviados na solicitação.

Crie um fluxo usando o gatilho da REST API

Crie um fluxo que começa quando um sistema de terceiros envia uma solicitação REST para sua instância.

Antes de Iniciar

Função necessária: Flow_designer ou admin.

Este recurso requer um IntegrationHub assinatura. Para obter mais informações, consulte Cronogramas jurídicos - Visão geral do IntegrationHub.

Procedimento

Aberto Workflow Studio e criar um fluxo.

Consulte Crie um fluxo .

Lembre-se de que o escopo do fluxo está incluído no endpoint REST que você cria.
Em GATILHO , selecione REST API - Assíncrono gatilho.
Em Método HTTP , defina o método HTTP para o endpoint.
As opções incluem:
- POST
- GET
- DELETE
- PUT
- PATCH
Crie todos os parâmetros de caminho necessários para o endpoint e adicione-os ao caminho relativo no Caminho campo.
O caminho relativo para o endpoint está no formato /api/<flow-application-scope>/<flow-name>/<path-parameters> .
Você pode clicar em Cópia para copiar o caminho completo para o endpoint. Use este caminho ao configurar o endpoint para a chamada REST em seu sistema de terceiros.
1. Crie variáveis no Parâmetros de caminho seção.
2. Arraste a cápsula de dados que representa o parâmetro de caminho para a entrada vazia no Caminho campo.
  
  Este campo aceita somente cápsulas de dados do Parâmetros de caminho seção.
Selecione Requer autenticação Para exigir cabeçalhos de autenticação na solicitação REST DE entrada.
Se Requer autenticação estiver selecionado, adicione as funções necessárias para autorizar a solicitação no Requer funções campo.
Em Corpo campo em Conteúdo da solicitação crie um objeto de dados complexo que defina a estrutura do corpo da solicitação de entrada.

Para obter mais informações sobre como criar um objeto complexo, consulte Dados complexos .

Nota:
. Conteúdo da solicitação a seção só aparece quando Método HTTP É POST, PUT ou PATCH.

Este corpo de exemplo encontra o campo Descrição em uma carga de entrada que contém informações de tíquete de um sistema de acompanhamento de tíquete de terceiros.
Em Cabeçalhos defina os cabeçalhos a serem enviados na solicitação de entrada.
Você pode selecionar Obrigatório exigir que a solicitação de entrada os inclua.
Em Parâmetros de consulta defina os parâmetros de consulta a serem enviados na solicitação de entrada.
Você pode selecionar Obrigatório exigir que a solicitação de entrada os inclua.
Adicione ações ao seu fluxo que são executadas quando o endpoint é chamado.

Você pode usar as cápsulas de dados do gatilho DA REST API em suas ações de fluxo.

Esta ação cria um registro de incidente e mapeia os campos Descrição e Grupo de atribuição da carga de entrada para o incidente.
Teste e ative o fluxo.
Para obter mais informações, consulte Teste um fluxo e. Ativar um fluxo .
Uma vez ativado, o endpoint é exibido no Explorador DA REST API. Você pode usar esta página para testar ainda mais seu endpoint ou configurar a solicitação do seu sistema de terceiros.

Configure a solicitação REST do seu sistema de terceiros.

Por exemplo, você pode enviar esta solicitação cURL para acionar o fluxo definido nas etapas anteriores.

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'

Resultado

O fluxo é executado e a solicitação REST retorna o ID de execução.

{
  "result": {
    "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO"
  }
}

O que Fazer Depois

Copie o ID de execução no resultado e navegue até a guia Execuções no Flow Designer. Você pode filtrar por ID de execução para localizar os detalhes da execução e exibir o status da execução.

Para solucionar problemas, você pode depurar a consulta REST ou verificar os detalhes da execução do fluxo. Consulte Depurar consultas REST e. Detalhes da execução do fluxo .