# Trigger Workflow via WebHook

Nected allows you to securely initiate a workflow from your systems using a Webhook URL. This feature enables you to pass custom parameters and retrieve all pertinent information related to the workflow, ensuring seamless integration and efficient data handling.

To trigger a workflow via webhook, follow these steps:

1. **Test and Publish the Workflow**: Ensure the workflow you want to trigger is tested and published.
2. **Access the Trigger Node**:

   * Go to the **Trigger Node** and click on it.
   * Navigate to the **Settings** tab, where you will find the API and WebHook URL information.

   ![](https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FxqMGQJ6rCun1SHjMmOsV%2Fimage.png?alt=media\&token=3d8e3470-923a-4ad8-95cf-3ba37de9e80f)
3. **Use the WebHook URL**:
   * The **Settings** tab will display the WebHook URL, which contains all the information and behavior of the workflow trigger.
   * Use the URL to trigger the workflow via WebHook. Below is the URL:

```jsx
<https://nected-xx.nected.io/nected/webhook/{env}/workflow/{id}/{version}>
```

The WebHook URL consists of the following components:

* **Base URL**: `https://nected-xx.nected.io/nected/webhook`
* **env**: The environment of the rule, either `staging` or `production`.
* **entity\_name**: The name of the rule to be executed.
* **id**: The ID of the rule.
* **Version**: The version is optional, and will only appear if the rule environment if production.

{% hint style="warning" %}
**Note:**

**Two things you should be aware about while triggering a rule.workflow via API/Webhook:**

1. We currently support the POST method only
2. If you want to use the [Authorization](https://docs.nected.ai/nected-docs/security/api-authentication) for the API/Webhook of the rule/workflow trigger, copy the API key from the Authorization page. Below we've a [small section](#webhook-authentication) on how you can do this.
   {% endhint %}

Inside the '**How to Trigger?**' section you'll get this type of `cURL` code, which you can copy and use seamlessly:

```markup
curl -X "POST" "https://nected-xx.nected.io/nected/webhook/production/workflow/65df54bb85d91df40fxxxxx" \
     -H 'Content-Type: application/json' \
     -d $'{
  "Transaction_amt": 10000,
  "aoi": 100000,
  "customer_id": "customer1",
  "date": "21/02/2024",
  "n_list": [
    "ABC",
    [
      2000,
      "Nected",
      "2024-07-02"
    ],
    "2024-07-02T05:47:10Z",
    {
      "key_name_1": "Rule Engine",
      "key_name_2": true
    },
    true
  ],
  "sensor_id": "Prod12"
}'
```

Well, as we've multi-environment along with multiple versions, it can be confusing for you while working with the API. To minimize your confusion, here is a table clarifying the API behavior based on versions and different environments:

<table><thead><tr><th width="127">Version</th><th width="132">Environment</th><th width="296">View</th><th>Explanation</th></tr></thead><tbody><tr><td>✅</td><td>✅</td><td><p><code>"version":"version_value",</code></p><p><code>"environment":"env_value", (staging/production)</code></p></td><td>If in your webhook URL, both are written, then simply that specific version of workflow will be executed</td></tr><tr><td>✅</td><td>❌</td><td><code>"version":"version_value",</code><br><code>"environment":"production",</code></td><td>While calling the webhook, in the url, if you've not specified the <code>env</code> but you've specified the <code>version</code> then the default env i.e. <code>production</code> environment of that version will be executed</td></tr><tr><td>❌</td><td>✅</td><td><code>"version":"latest",</code><br><code>"environment":"env_value", (staging/production)</code></td><td>So, if you've not specified the version but the <code>env</code> then the webhook will execute the latest version of the rule of the environment that you've specified i.e. either staging or production.</td></tr><tr><td>❌</td><td>❌</td><td><code>"version":"latest",</code><br><code>"environment":"production",</code></td><td>If you've not specified anything in your webhook url, then by default the latest live/production version of the rule will be called and executed.</td></tr></tbody></table>

{% hint style="info" %}
This is how the webhook works, so if you're triggering the workflow via WebHook, make sure you follow this and call the webhook accordingly.
{% endhint %}

{% embed url="<https://www.youtube.com/watch?v=TY3CHz63SB4>" %}

As it can be visible, the base URL changed for staging and production like this:

1. Staging: `https://nected-XX.nected.io/nected/webhook/staging/workflow/{id}`
2. Production: `https://nected-XX.nected.io/nected/webhook/production/workflow/{id}/0.30`

Now, if you've multiple versions, and you want to trigger a specific version of the workflow via webhook, then you can follow this:

1. Go to the **Version Control** tab, and click on the "**Preview**" button for a specific version.
2. A new tab will be opened for that specific version. Then follow the same steps to go to the Webhook settings.
3. Then finally copy the URL and other fields.

### **Passing Custom Attributes Using Webhook**

* After Selecting the Webhook URL, you can use the webhook to pass the information as a custom attribute.
* To pass custom attributes in Workflow via using WebHook, You can use this flattened payload structure like this:

  ```jsx
  {
    "Transaction_amt": 10000,
    "aoi": 100000,
    "customer_id": "customer1",
    "date": "21/02/2024",
    "n_list": [
      "ABC",
      [
        2000,
        "Nected",
        "2024-07-02"
      ],
      "2024-07-02T05:47:10Z",
      {
        "key_name_1": "Rule Engine",
        "key_name_2": true
      },
      true
    ],
    "sensor_id": "Prod12"
  }
  ```
* Once You pass the payload, the webhook will not wait for the workflow execution it runs asynchronously backend. after its successful execution, it responds via a successful message.

### Webhook Authentication:

In case you want to authorize your trigger webhook for the rule, you simply follow these steps to do so:

{% stepper %}
{% step %}

### Turn on the authentication

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FN1sOEs2WdNZJfmSNGcAc%2Fimage.png?alt=media&#x26;token=d45be6ca-9fd4-42cc-85f6-4f0bd292c0a7" alt=""><figcaption></figcaption></figure>

Open the API settings, where the first is of Authentication. By default it will be "**None**". Just open the dropdown, and select "**Private**". This will turn on the authentication, and now the webhook will need the authorization key to be able to work. You can see that a new line i.e.&#x20;

```
-H 'nected-api-key: XXXX-XXXX-XXXX-XXXX'\
```

is now added in the header.
{% endstep %}

{% step %}

### Copy the Nected API key

Now, go to the Authorization page. And simply copy the nected-api-key, like this:

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FWHKFSIz5FgM7cnN5Lu0A%2Fimage.png?alt=media&#x26;token=70bf4c09-43a0-4ac5-9b9d-3b89461fd5d4" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Testing the Webhook

In case you're testing the Webhook on Postman, here is what you can do to test the API properly:

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FpthK6XIkf3YxSRM8grIf%2Fimage.png?alt=media&#x26;token=af024b0d-1403-4c43-a6b9-0e95622c6145" alt=""><figcaption></figcaption></figure>

First click on Authorization, and then from the auth type dropdown, select API key. Then add key-value and select Header from the "Add to" dropdown.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
For Webhook triggers, we currently support the POST method only.
{% endhint %}