Disparar uma operação do Studio a partir de um webhook no Jitterbit Studio

Introdução

O API Manager permite publicar uma operação do Studio como um endpoint HTTP. Quando um sistema externo envia uma solicitação HTTP para esse endpoint, o API Manager recebe a solicitação e executa imediatamente a operação vinculada, passando o corpo da solicitação e os headers através de variáveis do Jitterbit.

Esse padrão é útil para reagir a eventos em tempo real de sistemas externos, como plataformas CRM, ferramentas de suporte ou aplicações personalizadas que suportam webhooks de saída.

Este guia aborda o tipo Custom API no API Manager. Assume o seguinte:

Uma API personalizada está configurada e publicada no API Manager no mesmo ambiente do projeto.
Existe um projeto do Studio com pelo menos uma operação para receber a solicitação recebida.

O fluxo geral é:

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[Sistema externo] -->|HTTP POST| B[API Manager custom API] --> C[Operação do Studio] --> D[Resposta HTTP]

Parte 1: Criar a API personalizada

Etapa 1: Criar a API

Abra o API Manager e clique em New API.
Selecione Custom API como o tipo de API.
API Name: Digite um nome para a API (por exemplo, Webhook Receiver). Esse nome aparece no API Manager e nos logs de operação.
URL Prefix: Digite o segmento do caminho base para a URL do endpoint público (por exemplo, my-webhook).
Version: Digite uma string de versão (por exemplo, 1.0). Ela se torna parte da URL do endpoint.
Enable SSL: Ative para exigir conexões HTTPS. Isso é recomendado para todos os endpoints de produção.
Enable CORS: Ative se o sistema externo enviar solicitações cross-origin de um contexto de navegador.
Clique em Save.

Etapa 2: Configurar o endpoint de serviço

No editor de API, clique em Add Service.
Method: Selecione o método HTTP que o sistema externo usa para enviar o webhook (por exemplo, POST).
Path: Digite o sub-caminho do endpoint (por exemplo, /events). Ele é acrescentado à URL base.
Operation: Selecione a operação do Studio que processará a solicitação recebida.
Response Type: Selecione System Variable. Com essa configuração, o corpo da resposta é determinado pelo valor que a operação atribui a $jitterbit.api.response.
Timeout: Defina o tempo máximo que o API Manager aguarda a conclusão da operação. O padrão é 30 segundos.
Clique em Save e depois em Publish.

Após publicar, o API Manager exibe a URL completa do endpoint no formato https://<host>/<prefix>/<version>/<path>. Copie essa URL e configure o sistema externo para enviar payloads do webhook para ela.

Parte 2: Acessar o payload da solicitação na operação

Quando o API Manager dispara a operação vinculada, ele popula variáveis do Jitterbit com os dados da solicitação recebida. Leia essas variáveis em uma etapa de script no início da operação.

Variável	Conteúdo
`$jitterbit.api.request.body`	O corpo bruto da solicitação como uma string.
`$jitterbit.api.request.headers.content-type`	O valor do header `Content-Type` da solicitação.
`$jitterbit.api.request.headers.fulluri`	A URI completa da solicitação, incluindo o caminho. Útil para roteamento quando vários caminhos mapeiam para uma operação.
`$jitterbit.api.request.method`	O método HTTP da solicitação (por exemplo, `POST`).

O exemplo a seguir registra o corpo recebido e a URI no log de operação:

<trans>
WriteToOperationLog("Received body: " + $jitterbit.api.request.body);
WriteToOperationLog("URI: " + $jitterbit.api.request.headers.fulluri);
</trans>

Para usar o payload em uma transformação, atribua-o a uma variável e mapeie essa variável como a origem:

<trans>
$payload = $jitterbit.api.request.body;
</trans>

Rotear solicitações em vários caminhos

Se a API tiver vários caminhos de serviço (por exemplo, /createRecord e /updateRecord), você poderá mapear todos os caminhos para uma operação controladora única e usar uma instrução Case() para enviar para sub-operações com base na URI:

<trans>
Case(
  Index($jitterbit.api.request.headers.fulluri, "/createRecord") >= 0,
    RunOperation("<TAG>operation:Create Record</TAG>");,
  Index($jitterbit.api.request.headers.fulluri, "/updateRecord") >= 0,
    RunOperation("<TAG>operation:Update Record</TAG>");
);
</trans>

Isso mantém a configuração da API simples (um ponto de entrada único) enquanto a operação do controlador lida com a lógica de dispatch.

Parte 3: Retornar uma resposta para o chamador

Quando o Tipo de Resposta está definido como Variável de Sistema, o API Manager retorna o valor de $jitterbit.api.response como o corpo da resposta HTTP. Defina essa variável na operação antes de ela ser concluída.

O exemplo a seguir retorna uma confirmação JSON:

<trans>
$jitterbit.api.response = '{"status":"received"}';
</trans>

Se $jitterbit.api.response não estiver definido, o API Manager retorna uma resposta 200 OK vazia.

Para retornar um código de status HTTP diferente de 200, defina $jitterbit.api.response.status_code juntamente com o corpo da resposta:

<trans>
$jitterbit.api.response.status_code = "400";
$jitterbit.api.response = '{"error":"Missing required field"}';
</trans>

Nota

Alguns sistemas externos exigem uma resposta dentro de uma janela de tempo limite curta (geralmente de 3 a 10 segundos). Se a operação realiza trabalhos que consomem tempo, considere retornar uma confirmação imediatamente e processar a carga útil de forma assíncrona usando RunOperation com o parâmetro async definido como true.

Verificar a integração

Implante e execute o projeto.
No API Manager, copie a URL do endpoint publicado.
Envie uma solicitação POST de teste para o endpoint usando uma ferramenta como curl ou Postman, incluindo um corpo JSON.
Abra os registros de operação e confirme que a operação foi executada e que o corpo registrado corresponde à carga útil de teste.
Confirme que o corpo da resposta HTTP e o código de status correspondem aos valores definidos em $jitterbit.api.response e $jitterbit.api.response.status_code.