> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rwsintegration.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração acionada por Webhook

> Aprenda como configurar sua primeira integração acionada por webhook

Este guia mostra como criar uma integração que é acionada quando um webhook é chamado, transforma os dados recebidos e os envia para um endpoint de destino. Ao final, você entenderá como configurar integrações acionadas por webhook e testá-las usando cURL.

## O que você vai construir

Você criará uma integração que:

1. **Extrai** dados de requisições webhook recebidas
2. **Transforma** os dados mapeando campos para o formato de destino
3. **Envia** os resultados transformados para webhook.site onde você pode inspecioná-los

Tempo necessário: aproximadamente 5 minutos.

## Pré-requisitos

* Acesso a um Workspace da RWS Integration
* Um navegador web
* cURL (ou ferramenta de linha de comando similar) para acionar o webhook

<Tip>
  Certifique-se de estar no Workspace correto usando o seletor de workspace na barra lateral antes de começar.
</Tip>

## Passo 1: Configure seu destino

Antes de criar a integração, crie um endpoint de destino onde você pode verificar os resultados.

1. Abra [webhook.site](https://webhook.site) em uma nova aba do navegador
2. O site gera automaticamente uma URL única (ex.: `https://webhook.site/abc123-def456-...`)
3. **Copie a parte do caminho único** (ex.: `/abc123-def456-...`), pois você precisará dela ao configurar a fase de Envio
4. Mantenha esta aba aberta para monitorar requisições recebidas

<Note>
  webhook.site é um serviço gratuito que captura e exibe requisições HTTP. É útil para testar integrações antes de conectar a sistemas de destino reais.
</Note>

## Passo 2: Crie a conexão de webhook

Conexões definem como a RWS Integration se comunica com sistemas externos. Você criará uma para a fonte webhook.

1. Na barra lateral, clique em **Conexões**
2. Clique em **Nova Conexão**
3. Configure a conexão:

| Campo  | Valor                              |
| ------ | ---------------------------------- |
| Nome   | `[Doc] Webhook Extract Connection` |
| Versão | `1.0.0`                            |
| Tipo   | `Webhook`                          |

4. Clique em **Salvar**
5. **Copie o ID da conexão**: você pode encontrá-lo na URL após criar a conexão. Você precisará deste ID ao acionar o webhook com cURL.

## Passo 3: Crie a conexão de destino

Agora crie uma Conexão para seu destino webhook.site.

1. Clique em **Nova Conexão**
2. Configure a conexão:

| Campo                        | Valor                                |
| ---------------------------- | ------------------------------------ |
| Nome                         | `[Doc] Webhook Site Load Connection` |
| Versão                       | `1.0.0`                              |
| Tipo                         | `API`                                |
| URL                          | `https://webhook.site`               |
| Caminho base (URL base path) | `/`                                  |
| Autenticação                 | `Sem autenticação`                   |

3. Clique em **Salvar**

## Passo 4: Crie a Integração

Com ambas as Conexões prontas, crie a Integração que processa requisições webhook e as entrega ao seu destino.

1. Na barra lateral, clique em **Integrações**
2. Clique em **Nova Integração**

### Configurações gerais

Configure as propriedades básicas da integração:

| Campo       | Valor                       |
| ----------- | --------------------------- |
| Nome        | `[Doc] Webhook Integration` |
| Versão      | `1.0.0`                     |
| Tipo        | `Full`                      |
| Ambiente    | `Staging`                   |
| Agendamento | Diária, em qualquer horário |

<Note>
  Estamos usando o ambiente **Staging** para testes. Quando estiver pronto para implementar em produção, você pode alterar isso para **Production**. A RWS Integration mantém esses ambientes separados para que você possa testar alterações com segurança antes de colocar em produção.
</Note>

<Note>
  Para integrações acionadas por webhook, o **Agendamento** é obrigatório mas não é usado ativamente: webhooks acionam a integração sob demanda quando requisições são recebidas, então qualquer frequência funciona aqui.
</Note>

### Fase de Extração

A fase de Extração recebe dados de requisições webhook recebidas.

1. Expanda a seção **Extração**
2. Configure estes campos:

| Campo   | Valor                              |
| ------- | ---------------------------------- |
| Conexão | `[Doc] Webhook Extract Connection` |

<Note>
  Ao usar uma conexão webhook, a RWS Integration recebe automaticamente o corpo da requisição de chamadas webhook recebidas. Você não precisa configurar um método ou caminho.
</Note>

3. O webhook aceitará requisições POST recebidas com payloads JSON. Você pode adicionar um corpo de exemplo ao painel **Preview de Extração** para disponibilizá-lo para o **preview** da **transformação** e **envio**:

```json theme={null}
{
  "id": "1234567890",
  "description": "Item description"
}
```

### Fase de Transformação

A fase de Transformação mapeia campos de origem da requisição webhook para o formato de destino. Para este guia, crie um mapeamento simples com dois campos.

1. Expanda a seção **Transformação**
2. Clique em **Adicionar Transformação** e configure:

| Tipo    | Para              | De            |
| ------- | ----------------- | ------------- |
| Simples | `externalId`      | `id`          |
| Simples | `itemDescription` | `description` |

3. Verifique o painel **Preview de Transformação**. Ele deve exibir a estrutura transformada com base em dados de exemplo:

```json theme={null}
{
  "externalId": "1234567890",
  "itemDescription": "Item description"
}
```

Isso confirma que seus mapeamentos estão funcionando corretamente e mostra como os dados do webhook serão transformados.

<Note>
  O Preview de Transformação usa dados de exemplo para demonstrar a transformação. Quando você acionar o webhook com dados reais, eles serão transformados de acordo com esses mapeamentos.
</Note>

### Fase de Envio

A fase de Envio envia dados transformados para seu destino.

1. Expanda a seção **Envio**
2. Configure estes campos:

| Campo              | Valor                                                         |
| ------------------ | ------------------------------------------------------------- |
| Conexão            | `[Doc] Webhook Site Load Connection`                          |
| Método             | `POST`                                                        |
| Caminho (URL path) | Seu caminho único do webhook.site (ex.: `/abc123-def456-...`) |
| Tipo de Envio      | `Simples`                                                     |

<Warning>
  Copie apenas a parte do caminho da sua URL do webhook.site. Se sua URL completa for `https://webhook.site/abc-123`, insira `/abc-123` como o Path.
</Warning>

3. Verifique o painel **Preview de Envio**. Ele mostra a requisição completa que será enviada:
   * **Path**: URL completa de destino
   * **Method**: POST
   * **Request Body**: Sua estrutura de dados transformada

<Note>
  O Preview de Envio não envia dados ao destino: ele apenas mostra o que será enviado quando você executar a integração. Isso permite validar sua configuração com segurança antes de executar.
</Note>

## Passo 5: Crie a Integração

1. Ative o toggle **Implantação**
2. Clique em **Criar Integração**

A integração agora está ativa e pronta para receber requisições webhook. Diferente de integrações agendadas, integrações webhook aguardam requisições recebidas em vez de executar em um agendamento.

## Passo 6: Acione e verifique a integração

Agora teste sua integração enviando uma requisição webhook usando cURL.

Substitua os seguintes placeholders no comando cURL:

* `{{ tenantId }}` - O ID do tenant da sua organização (você pode encontrá-lo na URL do workspace da RWS Integration)
* `{{ webhookId }}` - O ID da conexão webhook do Passo 2 (você pode encontrá-lo na URL da página da conexão webhook)
* `{{ apiKey }}` - Sua chave de API da RWS Integration (entre em contato com a equipe da RWS Integration se necessário)

Execute o seguinte comando cURL:

```bash theme={null}
curl -X POST "https://api.rwsintegration.com/v1/webhook?tenantId={{ tenantId }}&webhookId={{ webhookId }}" \
  -H "x-api-key: {{ apiKey }}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1234567890",
    "description": "Item description"
  }'
```

<Check>
  Você deve receber uma resposta similar a:

  ```json theme={null}
  {
    "success": true,
    "message": "1 jobs queued for 1 integrations",
    "jobIds": [
      "1234567890"
    ],
    "integrationCount": 1
  }
  ```

  Em alguns segundos, mude para a aba do webhook.site no seu navegador. Você deve ver uma requisição POST recebida contendo sua estrutura de dados transformada:

  ```json theme={null}
  {
    "externalId": "1234567890",
    "itemDescription": "Item description"
  }
  ```

  Isso confirma que sua integração webhook recebeu com sucesso a requisição, transformou os dados e os entregou ao destino.
</Check>

<Tip>
  Você também pode testar sem cURL: abra a integração e clique em **Executar agora**, ao lado do botão **Salvar**. Para integrações webhook, o diálogo pede o payload JSON que o webhook receberia. Ele vem preenchido com o corpo de exemplo do preview (se você tiver informado um) ou com o último payload usado.
</Tip>

Parabéns! Você criou e testou sua primeira integração acionada por webhook!

## Entrega assíncrona

Por padrão, o webhook responde depois de terminar de processar a requisição. Se o provedor que faz a chamada impõe um tempo limite curto, ele pode desistir antes de a resposta chegar e reenviar o mesmo evento, causando duplicatas.

Adicione `async=true` à URL do webhook para que ele responda imediatamente e processe a requisição em segundo plano.

```bash theme={null}
curl -X POST "https://api.rwsintegration.com/v1/webhook?tenantId={{ tenantId }}&webhookId={{ webhookId }}&async=true" \
  -H "x-api-key: {{ apiKey }}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1234567890",
    "description": "Item description"
  }'
```

A resposta confirma que a requisição foi aceita:

```json theme={null}
{
  "success": true,
  "message": "Webhook accepted for asynchronous processing"
}
```

Confira os resultados no [Monitoramento](/pt-br/core-concepts/monitoring).

## O que você aprendeu

* **Integrações** seguem o padrão Extração → Transformação → Envio (com Enriquecimento opcional)
* **Conexões webhook** recebem requisições recebidas em vez de fazer chamadas de API de saída
* **Painéis de Preview** atualizam automaticamente conforme você configura cada fase, permitindo validar antes de executar
* **Transformações simples** mapeiam campos da origem para o destino usando notação JSONPath
* **Como acionar a integração webhook** com uma requisição POST usando cURL
* **Modos de entrega**: síncrono por padrão, ou assíncrono com `async=true` para provedores com timeouts curtos

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conexões" icon="plug" href="/pt-br/features/connections/api">
    Aprenda sobre os diferentes métodos de autenticação
  </Card>

  <Card title="Mapeamento de Dados" icon="arrow-right-arrow-left" href="/pt-br/core-concepts/data-mapping">
    Transforme dados entre formatos de origem e destino
  </Card>

  <Card title="Regras de Negócio" icon="code" href="/pt-br/features/business-rules/overview">
    Domine transformações de campos com JavaScript
  </Card>

  <Card title="Monitoramento e Depuração" icon="chart-line" href="/pt-br/core-concepts/monitoring">
    Observe e solucione problemas de execuções de integração
  </Card>
</CardGroup>