Webhook

Overview

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.

Prerequisites

Before initiating the integration, ensure the following requirements are met:

• An external system capable of sending outbound HTTPS POST requests with a JSON body.

• A Digital Worker (or workflow) that the webhook will trigger.

• A valid user email address to include in the request payload.

• A REST client such as Postman for testing the webhook before wiring up the external system.

• Network connectivity from the external system to the Spool platform over HTTPS.

Setup Instructions

Step 1 – Access the Integrations Module

1. Log in to the Spool platform using an Admin account.

1. Navigate to Settings → Integrations.

1. Click the "+ Add Integration" button to view available integrations.

1. Search for Generic Webhook and select the integration.

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.

Webhook URL and Token

Once the integration is created, open it to view the generated webhook API URL. This is the endpoint the external system will call.

https://<platform-domain>/api/v1/webhook/generic/<token>

• 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": "whats the weather today",

"Useremail": "[e-mail]",

"externalId": "REQ-1234785",

"attributes": {

"city": "Austin",

"State": "TX"

}

}

}

Field reference

Field	Type	Required	Description
generic event	Object	Yes	Root wrapper object. All event data is nested inside it.
query	String	Yes	The instruction or message passed to the Digital Worker (for example, "whats the weather today"). This is what the LLM reasons over.
Useremail	String	Yes	Email address of the user the event is associated with. This is the only mandatory field — requests without it will fail.
externalId	String	No	Identifier of the originating record in the external system (for example, a request or work order number). Useful for traceability.
attributes	Object	No	Free-form key/value pairs carrying any additional context the Digital Worker may need (for example, city and state).

Note: every field except Useremail is optional — omitting them will not produce an error. Field names are case-sensitive and must be sent exactly as shown above.

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.

1. Open the Digital Worker you want the event to invoke.

2. Add a trigger and select the Generic Webhook integration you created.

3. Any request delivered to that webhook URL will now invoke the Digital Worker, and the query is passed in as its input. It makes no difference whether the caller is an external ITSM system, a scheduled job, Postman, or JavaScript inside another integration’s code task — the behaviour is identical.

4. If the Digital Worker only needs to reason over the payload, its instructions alone are sufficient — no tools are required.

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

Validation & Verification

1. Upon successful creation, a confirmation message is displayed and the integration is added.

2. Navigate back to the Integrations tab and verify that the newly added integration appears at the top of the list.

3. Copy the webhook URL and send a test POST request from Postman using the sample payload above.

4. Confirm that a success response is returned.

5. Open the Digital Worker’s run history and confirm that a new execution was triggered with the payload you sent.

Best Practices

• Protect the webhook URL: the token is the only access control. Store it as a secret in the external system and rotate the integration if it is ever exposed.

• Always send Useremail: it is the one mandatory field, and it associates the event with a user in the platform.

• Use externalId for traceability: populating it with the source record identifier makes it far easier to correlate a Digital Worker run back to the originating ticket or work order.

• Keep attributes purposeful: pass only the context the Digital Worker actually needs. A flat, well-named set of keys is easier for the worker’s instructions to reason over than a deeply nested dump.

• Test with Postman first: validate the payload and confirm the Digital Worker runs before wiring the external system up to the URL.

• One webhook per use case: create a separate integration for each source system or event type rather than multiplexing everything through a single URL. This keeps triggers, naming, and troubleshooting clean.

• Handle retries on the caller side: if the external system retries failed deliveries, make sure repeated events are safe — each delivery triggers a Digital Worker run.

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.