> ## 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.

# Integration with Webhook Trigger

> Learn how to set your first integration triggered by a webhook

This guide walks you through creating an integration that triggers when a webhook is called, transforms the incoming data, and delivers it to a destination endpoint. By the end, you'll understand how to set up webhook-triggered integrations and test them using cURL.

## What you'll build

You'll create an integration that:

1. **Extracts** data from incoming webhook requests
2. **Transforms** the data by mapping fields to your destination format
3. **Loads** the transformed results to webhook.site where you can inspect them

Time required: approximately 5 minutes.

## Prerequisites

* Access to an RWS Integration Workspace
* A web browser
* cURL (or similar command-line tool) for triggering the webhook

## Step 1: Create the webhook connection

Connections define how RWS Integration communicates with external systems. You'll create one for the webhook source.

1. In the sidebar, click **Connections**
2. Click **New Connection**
3. Configure the connection:

| Field   | Value                              |
| ------- | ---------------------------------- |
| Name    | `[Doc] Webhook Extract Connection` |
| Version | `1.0.0`                            |
| Type    | `Webhook`                          |

4. Click **Save**
5. **Copy the connection ID**; you can find it in the URL after creating the connection. You'll need this ID when triggering the webhook with cURL.

## Step 2: Create the destination connection

Now create a Connection for your webhook.site destination.

1. Click **New Connection**
2. Configure the connection:

| Field          | Value                                |
| -------------- | ------------------------------------ |
| Name           | `[Doc] Webhook Site Load Connection` |
| Version        | `1.0.0`                              |
| Type           | `API`                                |
| URL            | `https://webhook.site`               |
| Base Path      | `/`                                  |
| Authentication | `No authentication`                  |

3. Click **Save**

## Step 3: Set up your destination

Before building the integration, create a destination endpoint where you can verify the results.

1. Open [webhook.site](https://webhook.site) in a new browser tab
2. The site automatically generates a unique URL (e.g., `https://webhook.site/abc123-def456-...`)
3. **Copy the unique path portion** (e.g., `/abc123-def456-...`); you'll need it when configuring the Load phase
4. Keep this tab open to monitor incoming requests

<Note>
  webhook.site is a free service that captures and displays HTTP requests. It's useful for testing integrations before connecting to real destination systems.
</Note>

## Step 4: Create the Integration

With both Connections ready, create the Integration that processes webhook requests and delivers them to your destination.

1. In the sidebar, click **Integrations**
2. Click **New Integration**

### General settings

Configure the basic integration properties:

| Field       | Value                       |
| ----------- | --------------------------- |
| Name        | `[Doc] Webhook Integration` |
| Version     | `1.0.0`                     |
| Type        | `Full`                      |
| Environment | `Staging`                   |
| Schedule    | Daily, at any time          |

<Note>
  For webhook-triggered integrations the schedule is required but not actively used: webhooks trigger the integration on demand when requests arrive, so any frequency works here.
</Note>

### Extract phase

The Extract phase receives data from incoming webhook requests.

1. Expand the **Extract** section
2. Configure these fields:

| Field      | Value                              |
| ---------- | ---------------------------------- |
| Connection | `[Doc] Webhook Extract Connection` |

<Note>
  When using a webhook connection, RWS Integration automatically receives the request body from incoming webhook calls.
</Note>

3. The webhook will accept incoming POST requests with JSON payloads. You can add a sample body to the **Extract Preview** panel to make it available for **transformation** and **load** **previewing** in the next phases:

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

### Transform phase

The Transform phase maps source fields from the webhook request to your destination format. For this guide, create a simple mapping with two fields.

1. Expand the **Transform** section
2. Click **Add Transformation** and configure:

| Type   | To                | From          |
| ------ | ----------------- | ------------- |
| Simple | `externalId`      | `id`          |
| Simple | `itemDescription` | `description` |

3. Check the **Transform Preview** panel. It should display the transformed structure based on sample data:

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

This confirms your mappings are working correctly and shows how the webhook data will be transformed.

### Load phase

The Load phase sends transformed data to your destination.

1. Expand the **Load** section
2. Configure these fields:

| Field      | Value                                                      |
| ---------- | ---------------------------------------------------------- |
| Connection | `[Doc] Webhook Site Load Connection`                       |
| Method     | `POST`                                                     |
| Path       | Your webhook.site unique path (e.g., `/abc123-def456-...`) |
| Load Type  | `Simple`                                                   |

<Warning>
  Copy only the path portion from your webhook.site URL. If your full URL is `https://webhook.site/abc-123`, enter `/abc-123` as the Path.
</Warning>

3. Check the **Load Preview** panel. It shows the complete request that will be sent:
   * **Path**: Full destination URL
   * **Method**: POST
   * **Request Body**: Your transformed data structure

## Step 5: Deploy the Integration

1. Toggle **Deployment** to enabled
2. Click **Create Integration**

The integration is now active and ready to receive webhook requests. Unlike scheduled integrations, webhook integrations wait for incoming requests rather than running on a schedule.

## Step 6: Trigger and verify the integration

Now test your integration by sending a webhook request using cURL.

Replace the following placeholders in the cURL command:

* `{{ tenantId }}` - Your organization's tenant ID (you can find it in the URL of the RWS Integration workspace)
* `{{ webhookId }}` - The webhook connection ID from Step 1 (you can find it in the URL of the webhook connection page)
* `{{ apiKey }}` - Your API key for RWS Integration (contact the RWS Integration team if needed)

Run the following cURL command:

```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>
  You should receive a response similar to:

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

  And in a few seconds, switch to your webhook.site browser tab. You should see an incoming POST request containing your transformed data structure:

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

  This confirms that your webhook integration successfully received the request, transformed the data, and delivered it to the destination.
</Check>

<Tip>
  You can also test without cURL: open the integration and click **Run now**, next to the **Save** button. For webhook integrations, the dialog asks for the JSON payload the webhook would receive. It comes prefilled with the sample body from the preview (if you entered one) or with the last payload you used.
</Tip>

Congratulations, you've built and tested your first webhook-triggered integration!

## Asynchronous delivery

By default the webhook responds after it finishes processing the request. If the calling provider enforces a short timeout, it may give up before the response arrives and resend the same event, causing duplicates.

Add `async=true` to the webhook URL to have it respond right away and process the request in the background.

```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"
  }'
```

The response confirms the request was accepted:

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

Check the results in [Monitoring](/en/core-concepts/monitoring).

## What you learned

* **Integrations** follow the Extract → Transform → Load pattern (with optional Enrichment)
* **Webhook connections** receive incoming requests rather than making outbound API calls
* **Preview panels** automatically update as you configure each phase, letting you validate before running
* **Simple transformations** map fields from source to destination using JSONPath notation
* **How to trigger the webhook integration** with a cURL POST request
* **Delivery modes**: synchronous by default, or asynchronous with `async=true` for providers with short timeouts

## Next steps

<CardGroup cols={2}>
  <Card title="Connections" icon="plug" href="/en/features/connections/api">
    Learn about different authentication methods
  </Card>

  <Card title="Data Mapping" icon="arrow-right-arrow-left" href="/en/core-concepts/data-mapping">
    Transform data between source and destination formats
  </Card>

  <Card title="Business Rules" icon="code" href="/en/features/business-rules/overview">
    Master field transformations with JavaScript
  </Card>

  <Card title="Monitoring & Debug" icon="chart-line" href="/en/core-concepts/monitoring">
    Observe and troubleshoot integration runs
  </Card>
</CardGroup>