Add Helix Plan webhooks

You can add webhooks that integrate Helix Plan with Helix DAM to share information between the applications. The Helix Plan webhooks integration requires Helix Plan Server 2024.2/010 and later and Helix Plan Web 2024.2/003 and later. Helix Plan webhooks can only be created at the company level, they cannot be created at the project level. After a Helix DAM company administrator adds a Helix Plan webhook, Helix DAM users can add Helix Plan item links to assets. Basic information about the Helix Plan item and a link is displayed with the asset. When the asset is updated, the webhook runs and information is automatically sent and displayed in the related Helix Plan item as a comment. To learn more about webhooks, see Webhooks.

You can also add custom webhooks to integrate Helix DAM with other external services. To learn more, see Add custom webhooks.

When webhooks run

Helix Plan webhooks run when users:

• Update assets, which includes:
  • Adding new asset versions
  • Moving assets
  • Renaming assets
  • Deleting assets
• Updating the status of assets from the Open state to an In progress or Closed state type. The webhook will not run for any other asset status change.

  For example, the webhook will not run if you change the asset status from an In progress state to a Closed state type.

• Add comments to assets

Step 1: Create an integration user

Before integrating Helix Plan with Helix DAM, create an Integration user and assign it as the Main manager in the required projects in Helix Plan.

1. Create an Integration user in Helix Plan.

   To create a user in Helix Plan, see Adding a team member to Helix Plan in the Helix Plan user documentation.

2. Set the user settings to Is a main manager to allow the webhook integration user to perform actions such as accessing projects, searching for items, and adding comments.

   To change user settings in Helix Plan, see Changing project user settings in the Helix Plan user documentation.

Step 2: Configure a webhook

1. In Helix DAM, click your user avatar and select Company settings.
2. From the Company settings pane, click Webhooks.
3. On the Webhooks page, click Add webhook.
4. On the Define details tab in the Add webhook pane, enter or select general information about the webhook.

   Field	Description
   Name	Enter a name for the webhook to distinguish it from other webhooks. For example, you may want to use Helix Plan to make it easily identifiable to users when they add links to assets.
   Type	Select Helix Plan. To add a custom webhook that integrates with other external services, see Add custom webhooks.
   Projects	By default, the webhook runs on all projects. To only run the webhook on specific projects, select the projects in the list. You can search for a project. To remove a selected project, click X next to it.
   Repositories/collections	By default, the webhook runs on all collections in the selected projects. To only run the webhook on specific collections, select the collections in the list. You can search for a collection. To remove a selected collection, click X next to it.
   Events that trigger webhook	By default, the webhook runs for all supported events for Helix DAM assets. To only run the webhook when specific events occur, select the events in the list. To remove a selected event, click X next to it.
   Interval	Select whether to run the webhook immediately after the event is performed or at a specified interval. An interval 5 minutes or more sends a batch of events that occur during the interval time.

5. Click Continue.
6. On the Configure webhook tab, enter or select the Helix Plan URL, authentication parameters, and advanced options to customize the webhook.

   Field	Description
   URL	Web client URL for Helix Plan to connect to Helix DAM.
   Insecure SSL	If Helix Plan uses an SSL certificate that cannot be verified, such as a self-signed certificate, select this option.
   Authentication parameters	Authenticate to Helix Plan using a username and either a token or a password. A token is valid for two years, but you can change the expiration date. To use a Helix Plan token, see Adding authentication tokens. A password is valid for one hour.
   Advanced settings	Optional. Click the arrow to expand the area and set the options. To override the default proxy configuration for the Helix DAM instance, select Use custom proxy configuration. Enter a Custom proxy URL or leave the field empty if you do not want to use a proxy. To restrict when webhooks run based on path or reference patterns, see Step 3: (Optional) Restrict when webhooks run.

7. Click Finish.

   The webhook is added. Users can now add Helix Plan links to Helix DAM assets. To learn more, see Work with links on assets.

   If you need to prevent the webhook from running temporarily, open the Webhooks pane, click for the webhook, and select Inactivate. The webhook is displayed as Inactive on the Webhooks pane. To learn more, see Manage webhooks.

   Tip

   If you cannot save the webhook because Helix DAM cannot communicate with Helix Plan, see Troubleshoot Helix Plan integration issues.

Step 3: (Optional) Restrict when webhooks run

By default, Helix DAM runs all active webhooks. You can use case-insensitive regular expressions to specify reference and path patterns that restrict when webhooks run.

Reference pattern

To restrict a webhook to only run when a branch or bookmark matches a pattern, specify a Reference pattern.

For example, to run a webhook only when branches named 'main' or 'develop' are updated, use this as the Reference pattern:

^(main|develop)$

To run a webhook only when feature branches are updated and the path is 'tests', use:

• ^feature as the Reference pattern

• tests as the Path pattern

Path pattern

To restrict a webhook to only run when a changed path matches a pattern, specify a Path pattern.

For example, to run a webhook only when JavaScript files are changed, leave the Reference pattern empty and use this as the Path pattern: .*\.js$.