Webhook Trigger Setup (Zip Integration)

Overview

This guide explains how to configure the Webhook trigger action in template workflows within TrustWorks. Webhooks enable external systems like Zip to trigger TrustWorks workflows in real time, for example, when a purchase order changes in Zip.

⚠️ Currently, only Zip integrations are supported with webhook triggers.

However, the implementation is designed to be extensible and support other platforms in the future.

Table of Contents

1. What is a Webhook Trigger
2. Requirements
3. Set Up the Zip Integration
4. Add a Webhook Trigger to a Workflow
5. Data Mapping
6. Webhook Payload Format
7. Testing the Integration
8. Troubleshooting

1. What is a Webhook Trigger?

A webhook trigger lets an external system send a POST request to TrustWorks to initiate a workflow automatically. For example:

“When a request is submitted in ZipHQ, trigger a workflow in TrustWorks to create a vendor asset.”

Currently, this functionality is available only within template workflows and only supports the Zip integration.

2. Requirements

Before you start, ensure the following:

• You have a TrustWorks admin account
• You are working within a template workflow
• A Zip integration is configured in your TrustWorks instance
• You have access to a Zip API key

3. Set Up the Zip Integration

To use webhook triggers with Zip, the integration must be configured in TrustWorks.

Steps:

• Go to Settings > Integrations  
• Click Add Integration and select Zip
• Enter your Zip API Key
• Click Generate Secret Key

⚠️ After generation, copy the secret key immediately. It is only visible once and will be required in the webhook URL to authenticate requests.

• Once you've generated the secret key in TrustWorks, you’ll need to configure the webhook in Zip. In Zip, go to Company Settings → API → Webhooks tab, and paste the following in the Target URL field:

<https://api.trustworks.io/v1.0/integrations/zip/webhook?secret_key=YOUR_SECRET_KEY>

• Lastly, select the events you'd like the webhook to subscribe to.

  

4. Add a Webhook Trigger to a Workflow

1. Navigate to Workflows  in your TrustWorks project
2. Open or create a template workflow
3. Drag the Webhook trigger node onto the canvas
4. Select your Zip integration and choose from one of the supported Zip event types (e.g. request.submitted  , approval.updated  )
5. Complete the rest of your workflow design based on your business logic.

The list of event types is currently hardcoded based on Zip’s available events. Support for custom events or other platforms may be added in future releases.

5. Data Mapping Using Jinja2 Templating

Data mapping lets you extract and transform data from incoming webhook payloads (like from Zip) to use in downstream workflow actions in TrustWorks. The logic can be as simple or complex as your use case requires.

Where to Add Data Mapping Logic

Add your Jinja2 mapping logic in the Body field of the API request action that follows the webhook trigger in your workflow.

• When a webhook fires (for example, when Zip sends a request.approved  event), workflow variables such as event_data   will be available for use.
• In the next step of your workflow, configure an HTTP Request Action (such as "Create Processing Activity," "Send Notification," or any custom HTTP request to one of our API endpoints).
• In that action’s setup screen, look for the body field.
• Paste or write your Jinja2 data mapping template in this field.
  • Use Jinja2 syntax to select fields, apply conditions, and output the values your TrustWorks API expects.

Example:

text{%- set important_field = (
  event_data.data.attributes
  | selectattr("config_id", "equalto", "<UUID>")
  | map(attribute="data")
  | list
  | first
  or ""
) %}

{
  "destination_field": "{{ important_field }}"
  // More mappings as needed
}

You can adjust this template for the data and logic your organization requires. The location of this mapping is always in the Body field of the relevant API request action in your workflow builder UI.

Example request:

Example Use Cases

• Creating or updating processing activities.
• Sending notifications based on approval status.
• Logging events for compliance tracking.

6. Webhook Payload Format

When the configured event occurs in ZipHQ (such as request.submitted  or approval.updated  ), Zip will automatically send a POST request to TrustWorks.

To ensure your workflow in TrustWorks is triggered properly, the request sent from Zip must include a valid event payload with the expected structure. The event_type  must exactly match the value selected in your workflow configuration.

Here is an example of the expected payload structure:

{
  "event_type": "request.submitted",
  "id": "123"
}

This payload will be sent automatically by Zip when the event is triggered.

TrustWorks will verify the webhook request using the secret_key  query parameter to identify the correct tenant and integration.

7. Testing the Integration

To test the integration, you can either:

1. Test it with with mock data, use curl  , Postman, or an API client of your choice:

curl --request POST \\
  --url '<https://api.trustworks.io/v1.0/integrations/zip/webhook?secret_key=YOUR_SECRET_KEY>' \\
  --header 'Content-Type: application/json' \\
  --data '{ "event_type": "request.submitted", "id": "123" }'

1. Test it directly by triggering the relevant webhook from Zip.

In TrustWorks, you can monitor the workflow execution directly from the Workflow Builder’s run history

💡 In the backend, TrustWorks uses event_type and secret_key to route the webhook to the correct integration and trigger the correct workflow.

8. Troubleshooting

Summary

Webhook triggers are a powerful way to initiate TrustWorks workflows from external events in real time. With the current Zip integration, teams can automate workflows such as:

• Creating vendor records from Zip approvals
• Kicking off risk reviews from third-party onboarding
• Logging metadata from external compliance events

More integrations will be supported over time, but for now, Zip is the first fully enabled webhook source.