Introduction

The Custom (Webhook) Trigger is a powerful addition to Torii's automation suite, designed to provide IT teams with unparalleled flexibility. With this feature, you can initiate Torii workflows from any external system by sending a webhook containing the specific data required for your automated processes. This means your automation is no longer constrained by Torii's direct integrations, empowering you to centralize and streamline workflows across your entire ecosystem.

1. Employee Onboarding Initiated from Ticketing Systems
Employee onboarding often begins with a ticket in tools like Jira, Freshservice, or other ticketing systems. With Torii's Custom Trigger, you can send a webhook whenever a new ticket is opened. Torii will parse the incoming data—such as employee details—and use it in workflow actions to automate provisioning and other onboarding tasks.

2. Real-Time Offboarding
Start offboarding workflows immediately when a user is terminated in HR or Identity Provider (IDP) systems by sending a webhook to Torii. While Torii supports real-time offboarding for some systems, this capability may not be available for all. The Custom Trigger fills this gap, ensuring no delay in revoking access or completing offboarding tasks.

How Custom Trigger Works

Let’s explore how to set up and use a Custom Trigger by walking through an example of triggering a user onboarding workflow from Jira.

1.  Select "Custom trigger (webhook)"

Start by selecting the Custom Trigger (Webhook) as the trigger type when creating your workflow.

2. Configure the trigger

• Provide an optional description for your trigger, such as "When a Jira ticket is opened."

• Configure the Webhook type dropdown:
  • Okta event hook - for webhooks coming from Okta. This automatically handles the required verification by Okta and processes the Okta webhook payload.
    For more information on configuring incoming Okta Event Hooks, refer to this guide.
  • monday.com webhook – For webhooks coming from monday.com. This option handles Monday’s URL verification process, which requires responding to a challenge during webhook setup. Torii automatically completes the verification and processes incoming webhook events.
    💡 Note: monday.com sends an initial verification request without the real payload. As a result, you may need to trigger the test twice in Torii to see the actual data flow - once for the URL verification, and a second time for the full payload.
    To learn how to configure webhooks in monday.com, refer to this guide.
  • Custom - For other webhook sources. 

• Torii will generate a unique webhook endpoint for the workflow. Copy this URL, as it will be used in Jira later.

3. Configure your other system to send a webhook to Torii

In this example, we'll demonstrate how to send a webhook from Jira. You should adapt these steps based on the specific system you are using.

Next, set up the webhook in Jira (or another system initiating the API call):

1. 1. Open Jira and navigate to System > Webhooks.
   2. Create a new webhook and paste the URL copied from Torii into the URL field.

3. Select the event to trigger the workflow. For this example, choose Issue Created.

Save the webhook.

Congratulations! You’ve successfully created a webhook that will trigger a Torii automation.

4. Test the trigger

• Return to Torii and click Test button in the trigger configuration panel. Torii will now listen for events sent to the generated endpoint.
• In Jira, create a new issue to simulate the triggering event. Make sure that a new issue contains all fields that are required for new employee onboarding, to use them in user provisioning actions later.
• Go back to Torii to confirm that the event was received.

Once a webhook is received, Torii will display a notification in the trigger details panel.

• Open the JSON payload to review the incoming data.
• The variables in the payload can now be used in subsequent workflow actions.

5. Add actions to the workflow

Add the necessary actions to your onboarding workflow, such as creating accounts or sending notifications. Leverage variables from the payload to dynamically personalize the actions.

Variables in the payload containing email values will automatically appear as options in user dropdowns (e.g., user, manager and more). These will be listed at the top of the dropdown menu for easy selection.

All variables received during the test call are accessible as personalization tokens, prefixed with Trigger.<variable_name>. For payloads with nested data, Torii supports up to six levels of hierarchy. Nested variables will include additional prefixes, such as Trigger.issue.fields.dueDate.

FAQ

1. Can I send data about multiple users in a single call?

No, arrays in the payload are not supported. Each call should contain data for a single user or entity. All arrays sent in the call will be omitted from the payload. Please note that you can still see the original payload on the Workflow audit page.

2. How many hierarchical levels can I send in the payload?
The payload is limited to six hierarchical levels. Any properties beyond the third level will be excluded. Please note that you can still see the original payload on the Workflow audit page.

3. What HTTP methods does Torii support?

Torii supports the following HTTP methods for the custom trigger API: POST, PUT, PATCH, and DELETE. The GET method is also supported, however the payload sent via GET won’t be parsed.

4. Is there a size limit for the payload?
Yes, the payload size is limited to 256 KB. Payloads exceeding this size will not be processed.

5. What are the rate limits?
The rate limit is 1000 requests per minute.

6. What happens if I test a workflow multiple times?
Each test removes the personalization tokens from the previous test. As a result, any actions using variables from the prior payload will become invalid.

7. Can I configure and activate a workflow with a custom trigger without performing a test?
Yes, you can configure and activate a workflow without running a test. However, without performing a test, you will not be able to use the incoming payload data in workflow actions.

8. Can I send data about an app and perform actions on it, such as updating its state or other details?
Not currently. At this time, only user field selection is supported in user dropdowns. However, you can trigger existing workflows via API to perform actions on apps and contracts.

9. What security measures are set to ensure the custom webhook trigger is only triggered by a trusted entity?
The custom webhook trigger uses Token Based Authentication. Each webhook gets an auto generated randomly secure and unique token that is required when sending a webhook trigger. The token is embedded in the URL of the webhook to ensure only allowed clients can trigger it.

Tip

You can trigger one Torii workflow from another by using a Torii custom action to call a custom webhook trigger workflow.