Automation external trigger guide rewrite #234
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR updates the documentation for triggering Vendasta platform automations, expanding from a basic API-only approach to cover multiple trigger methods (Webhook, API, and Zapier) with comprehensive implementation details.
- Corrected spelling from "efficienciencies" to "efficiencies"
- Added detailed sections explaining three types of external automation triggers
- Restructured content to distinguish between Webhook and API triggers with specific implementation guidance
Reviewed Changes
Copilot reviewed 1 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/Guides/Automate/TriggerAutomation.md | Comprehensive rewrite of automation trigger documentation, adding webhook and Zapier trigger options alongside existing API triggers, with detailed setup instructions and data passing examples |
| docs/Guides/Automate/webhook_object_id.png | New screenshot showing how Account ID is passed in webhook payloads to unlock automation actions |
| assets/images/automation_triggers.png | New screenshot illustrating the automation triggers interface in the Vendasta platform |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <[email protected]>
| **Automation external triggers** | ||
|
|
||
| ## Setup: | ||
| There are **three primary types** of external triggers for an Automation: ***Webhook***, ***API***, and ***Zapier***. The choice depends primarily on the level of security required for the operations involved, and also on the technologies the partner is already using and familiar with. |
There was a problem hiding this comment.
Technically automations with manual, api, webhook and zapier triggers can all be started by API or zapier.
Rather than say there are 3 types of automation triggers I would list all the automation triggers that can be started manually. I would then say there are 4 ways they can be started:
- By API: Great for secure requests from your own servers.
- Using Zapier: For easy connecting to systems Vendasta does not have a built in integration with
- As a webhook: This option is only available for the webhook trigger (although I think we generate webhook URLs & keys for all automations)
- In platform: Triggers with "manual" in the name will appear at various locations within the platform.
The webhook trigger is was originally an API trigger that didn't require an entity. When support for calling it with an API key in the URL was added the UI was modified to rename it. Behind the scenes it can be called either way.
The zapier trigger also uses the /app/automata/api/no-entity-trigger event under the hood.
The automation picker in Zapier is supposed to show all automations where the canStartManually field is true. The API also returns a list of the fields that are supposed to be pass in. https://github.com/vendasta/api-gateway/blob/bcf2de7dfeea29496c169548a899d1dde617258e/internal/resource/automations.go#L148-L149
There was a problem hiding this comment.
I can adjust some of the wording as I like what you have there. I could mention how the in platform triggering of manual is a thing, however, I was focusing the article on programatic side of things. In platform can be covered by the help center docs.
I was trying to keep the tangle that is what's triggerable simple. Just because they could implement any of these in different ways doesn't mean they should. As such I ignored the overlap of the API & manual triggers, as well as the fact webhook and zapier could be triggered via API etc.
We did discuss treating the webhook trigger as the catch all for API triggering since it didn't have the object type restriction, but decided that if the point of calling via API vs Webhook was security, then having an open endpoint floating about defeated that purpose... however if we generate webhook urls behind the scenes for all of these triggers, then that's a moot point and we should just document the webhook and Zapier triggers until we can straighten this all out on the back end?
There was a problem hiding this comment.
I took a look at the code. We do generate the webhook URL, like I thought, but it returns an error if a different trigger is used.
I agree that we should keep it simple for now. We should eventually deprecate the entity specific API triggers and restore the UI for the entityless version.
The legacy guide only mentions a single one of the api endpoints, and is vague as it is, and generally useless.
The new guide covers