> For the complete documentation index, see [llms.txt](https://kb.theloops.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.theloops.io/agentstudio/integrations/generic-webhook.md).

# Generic Webhook

## Overview <a href="#overview" id="overview"></a>

The Generic Webhook Integration allows any external system to push events into the platform in real time, without building a dedicated, system-specific connector for each source. Where purpose-built connectors (such as IFS Assyst) require connector-level changes to support each new event type, the Generic Webhook accepts a standard JSON payload from any caller and routes it straight into a Digital Worker.
\
Each Generic Webhook integration is issued its own webhook URL containing a unique token. That token is how the platform distinguishes one webhook integration from another — there is no OAuth 2.0 flow, no token exchange, and no credential setup. Any request delivered to the URL triggers the Digital Worker that the integration is attached to, and the request body is passed through as the worker’s input.

### Best practices <a href="#best-practices" id="best-practices"></a>

* Protect the webhook URL. The token in the URL is the only access control. Store it as a secret in IFS Cloud and recreate the integration if it is ever exposed.
* Narrow the IFS Cloud event condition to the specific state transition you care about, so the Digital Worker is not triggered on every save.
* Always send Useremail. It is what associates the event with a user and gives the Digital Worker an identity to act on behalf of.
* Send externalId explicitly rather than relying on the TaskSeq / ReqID fallback.
* Keep attributes flat. Nested objects are stored as JSON text, which is harder for the Digital Worker to reason over.
* Test with curl or Postman before wiring up the IFS Cloud event action.
* Create one integration per use case rather than multiplexing event types through a single URL.

### Prerequisites&#x20;

Before initiating the integration, ensure the following requirements are met:&#x20;

* An IFS Cloud environment where you can create custom events and event actions.&#x20;
* A Digital Worker that the webhook will trigger.&#x20;
* A REST client such as Postman or curl, for testing the webhook before wiring up IFS Cloud.&#x20;
* Network connectivity from your IFS Cloud environment to the Spool platform over HTTPS.&#x20;

## Setup instructions

#### Access the Integrations Module

{% stepper %}
{% step %}
Log in to the Spool platform using an Admin account.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2FPwOejeux20pGkqqoIReZ%2FPicture1.png?alt=media&amp;token=c2d1b305-bced-43f1-84c6-3ad1611e661d" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Navigate to **Settings → Integrations**.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2FxzvwUoBB6yB9J0mBOWwL%2FPicture2.png?alt=media&amp;token=66b8f9d2-a3da-40e7-ad58-b79045aaf126" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Click the "**+ Add Integration**" button to view available integrations.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2Fca0lZH6rWrzVLM3Ga4Xl%2FPicture3.png?alt=media&amp;token=2f6d0f69-0f60-467f-afd5-0731f48e9bf4" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Search for **Generic Webhook** and select the integration.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2F7FbrVRyHuiB8ORknVN4y%2FPicture4.png?alt=media&amp;token=8f8edf73-c025-47c9-89b9-7ad48fc552dc" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

#### Step 2 – Basic Configuration

1\.   In the configuration tab, enter a suitable name for the integration. Use a name that identifies the source system or use case, since the name is how you will recognise this webhook later.

2. Click Connect to proceed.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2FfpIAwOkRKAcPKBRYWP6l%2FPicture5.png?alt=media&amp;token=3b63f3b0-6479-4e28-a190-11f4b1b32855" alt=""><figcaption></figcaption></figure>

#### Webhook URL and Token

* Once the integration is created, open it to view the generated webhook URL. This is the endpoint IFS Cloud will call.

  ```
  POST  https://<platform-domain>/conversation/v1/webhooks/<token>/ifscloud/ticket 

  Content-Type: application/json 
  ```
* The token at the end of the URL is unique per integration and is what identifies which webhook — and therefore which Digital Worker — the incoming event belongs to.
* Because the token is the only thing gating access, treat the full webhook URL as a secret. Anyone who has it can trigger the Digital Worker.
* Copy the URL and store it in the external system’s webhook configuration (or in Postman, for testing).

#### Request Payload

The webhook accepts a JSON body sent as an HTTP POST. No authorization headers are required.

```
POST  https://<platform-domain>/api/v1/webhook/generic/<token>
Content-Type: application/json
```

Sample request body

```
{ 
  "generic event": { 
    "query": "Summarise the completed work and draft the close-out note", 
    "Useremail": "customer@example.com", 
    "externalId": "REQ-1234785", 
    "attributes": { 
      "TaskSeq": "100234", 
      "Rowstate": "WORKDONE", 
      "Description": "Replace conveyor drive belt", 
      "city": "Austin", 
      "State": "TX" 
    } 
  } 
} 
```

#### Field reference

| **Field**     | **Type** | **Required** | **Description**                                                                                                                                                                                                                                                                                                                            |
| ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| generic event | Object   | Yes          | Root wrapper. All event data is nested inside it, and every field below is read from within it.                                                                                                                                                                                                                                            |
| query         | String   | Yes          | Free-text instruction or message passed through to the Digital Worker as the event’s query. A non-string value is ignored rather than treated as an error.                                                                                                                                                                                 |
| Useremail     | String   | Recommended  | Email address used for user get-or-create; it becomes the event’s triggering identity. The webhook also accepts userEmail or email, or a custom field name configured through the integration’s userEmailKey attribute. If none of those match, the payload is scanned recursively, so an email nested inside a sub-object is still found. |
| externalId    | String   | No           | External identifier for the event. If it is absent, the webhook falls back to the IFS Cloud keys TaskSeq and then ReqID when either is present in the wrapper.                                                                                                                                                                             |
| attributes    | Object   | No           | Free-form key/value pairs carrying any additional context the Digital Worker needs. Its keys are flattened into the event’s attributes map — primitive values as-is, nested objects and arrays as their JSON text. It must be a JSON object; an array or scalar is rejected.                                                               |

**Note:** inside the wrapper no field is structurally mandatory — a valid JSON object is accepted even if every key is missing. In practice Useremail should always be sent: without a resolvable email the event carries no triggering user, and the Digital Worker has no one to act on behalf of. Field names are case-sensitive and must be sent exactly as shown, wrapper key included.&#x20;

#### Triggering a Digital Worker

The webhook is only useful once it is attached to something. The flow is the same regardless of what sends the request.

{% stepper %}
{% step %}
Open the Digital Worker you want the event to invoke.
{% endstep %}

{% step %}
Add a trigger and select the IFS Cloud integration you created.
{% endstep %}

{% step %}
Any request delivered to the webhook URL now invokes the Digital Worker, and the request body is passed in as its input.
{% endstep %}

{% step %}
If the Digital Worker only needs to reason over the payload, its instructions alone are sufficient — no tools are required.
{% endstep %}

{% step %}
If the Digital Worker needs data that is not present in the payload (for example, resolving latitude and longitude before calling a weather API), add a tool such as a Code Task to fetch it.

<figure><img src="https://3180153102-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRIbp8Kp04VLXld01gmAs%2Fuploads%2FEWuLpr15qzHZ7MkblW2Q%2FPicture7.png?alt=media&amp;token=a5fb2bf8-a63e-4ecf-8710-5b86db20be3a" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### Validation & Verification

{% stepper %}
{% step %}
Upon successful creation, a confirmation message is displayed and the integration is added.&#x20;
{% endstep %}

{% step %}
Navigate back to the **Integrations** tab and verify that the newly added integration appears at the top of the list.&#x20;
{% endstep %}

{% step %}
Copy the webhook URL and send a test **POST** request from Postman using the sample payload above.
{% endstep %}

{% step %}
Confirm that a success response is returned.
{% endstep %}

{% step %}
Open the Digital Worker’s run history and confirm that a new execution was triggered with the payload you sent.
{% endstep %}
{% endstepper %}

### Current Limitations

The connector has intentionally been kept minimal for this release. The following are known constraints, with enhancements planned:

* No signature verification or OAuth 2.0. The URL token is the sole means of identifying and authorising a request.
* Any email value is accepted. Because the caller is an external system, the Useremail value is not validated against an authorised user list.
* No image or attachment support. Passing images in the payload is planned but not yet available.
* No ticket ID field. A dedicated ticket identifier is on the roadmap; use externalId in the meantime.
* No sample/test data in the connector UI. Use Postman with the sample payload above to test.