Webhook Triggers
Webhook triggers, also called Instant Triggers, are the most efficient type of triggers. 3rd-party systems push data via a webhook URL, which immediately results in an automation being executed.
Webhooks come in two variations:
- Webhooks that end users must manually configure in the 3rd-party app
- Webhooks that can be registered via the app's API
There are further variations within each of those:
- Webhooks with one event type per webhook URL
- Webhooks with multiple event types sent to a single webhook URL per customer account
- Webhooks with multiple event types and multiple customer accounts all delivered to a single webhook URL
All webhook triggers contain the Webhook module.
Some apps only allow webhooks to be manually configured by end users. For these apps, the Webhook module's Webhook URL field must be left blank:
When the Webhook URL field is blank, the module will generate a webhook URL when the assembly is either executed in the Assembly Editor (for testing) or in the automation editor. Configuration instructions should be entered instructing the end user how to configure the webhook in the app.
The Webhook module should have the Requires test transaction checkbox checked if the data schema for the webhook's payload is unknown or not always the same.
If the webhook always returns the same data schema, then uncheck the Requires test transaction checkbox and enter the output XML from the Webhook module into the Dynamic trigger fields XML field at the bottom of the Webhook module after running the assembly in the Assembly Editor first. This field XML defines the output fields emitted from the Trigger module.
The Webhook module parses the received webhook and emits data fields in a manner that can be directly consumed by the Trigger module. The Trigger module's unique row identifier field should be left empty for all webhooks.
Some API's provide endpoints for the registration and management of webhooks. API-Registered webhooks follow this basic pattern:
- When the webhook assembly is run in either the assembly or automation editor, the Generate Trigger Webhook URL or Generate Service Webhook URL subassemblies are used to create the webhook URL that will be fed into the Webhook module.
- When the webhook assembly is run in either the assembly or automation editor, the API endpoint to register the webhook URL with the app will be called.
- If the registered webhook is dangling because it was generated in the Assembly Editor or an automation was deleted or not completely built, the app's Delete Webhook assembly will be invoked by the system to unregister the webhook from the app.
The first step for registering a webhook URL via an API is to generate the webhook URL. This can only be done by either using the Generate Trigger Webhook URL or Generate Service Webhook URL subassemblies:
Both subassemblies accept a data parameter that can be supplied to facilitate the needs of the Delete Webhook assembly, to be discussed in the Dangling Webhooks section further below.
The next step is to conditionally register the webhook URL via the API:
The API endpoint to register the webhook URL should only be invoked when the assembly is being executed in the assembly or automation editor. The Utility – When In module and Conditional module above are used to determine when to invoke the subassembly to register the webhook URL.
Finally, the generated webhook URL is wired into the Webhook module's field:
The Configuration Instructions field is blank because the webhook is registered automatically via the API and the end user doesn't need to perform any configuration.
Webhooks that are registered via API have the risk of being left dangling.
A dangling webhook is one that is still registered with an app, but no automation is available to receive and process the webhook. So the app keeps sending the webhook needlessly.
Dangling webhooks can result from the following:
- Test webhook URLs are generated for use in the Assembly Editor to facilitate building and testing of the webhook trigger assembly
- An end user starts to build an automation with the webhook trigger but never saves the automation
- The automation is deleted
Developers of API-registered webhook triggers must build a Delete Webhook assembly that will unregister dangling webhooks via the app's API.
The assembly must be named exactly “Delete webhook”.
It is a type of action assembly. It should be made private, because it is not an action to be used in the automation editor. It is an action just so it appears in the Assembly Editor's catalog underneath the app.
Because it is an action, it must have an Action module which is unused.
The assembly can receive two query parameters named “webhook_url” and “data”, both of which can be received via the Query Parameter module.
The value of “webhook_url” will be the webhook URL that was registered with the API.
The value of “data” will be whatever data was supplied to either the Generate Trigger Webhook URL or Generate Service Webhook URL subassemblies:
The “data” value can be anything needed to facilitate deletion of the webhook.
The system will periodically scan the database for dangling webhooks, ones that are not associated with any automations. The system invokes the Delete Webhook assembly for any dangling webhooks it finds.
Don't forget to save your delete webhook assemblies as PRIVATE.
Most apps send one event type per webhook URL.
For example, a “new contact” event would be sent to webhook URL #1 and an “updated contact” event would be sent to a different webhook URL #2.
In this case, each event type maps to a separate webhook trigger assembly.
The Generate Trigger Webhook URL subassembly must be used when working with an app that sends one event type per webhook URL, for the case where they provide an API for registering webhooks.
The generated webhook URL will be of the form {SERVER_URL}/webhook/automation_uuid, which is to say that each event type is processed by a single automation.
Some apps send multiple event types to a single webhook URL for a given customer account.
For example, both “new contact” and “updated contact” and other events would all be delivered to a single webhook URL.
This type of webhook is called a Service Webhook.
In this case, the webhook URL maps to all the automations for the user that contain any webhook trigger. The webhook triggers have to inspect the webhook payload and only emit data if the payload contains data for the given trigger.
For example, a “new contact” trigger would inspect the payload and only emit data if the received event was a new contact.
The Generate Service Webhook URL subassembly must be used when working with an app that sends multiple event types to a single webhook URL.
The generated webhook URL will be of the form {SERVER_URL}/webhook/app_assembly_uuid-person_uuid, which is to say that the webhook is associated to the app and to the end user.
When the webhook is received the URL is parsed to determine the app and user account. Then all active automations for the user with triggers for the app are executed.
The best way to understand how to go about integrating webhooks is to view existing examples already in the system. Find the Webhook module, the Generate Trigger Webhook URL subassembly, and the Generate Service Webhook URL subassembly in the catalog, right-click on them, and find assemblies where they are used to examine existing implementations.
Some apps may use a single webhook for sending all activity in their entire system, for all customer accounts. MINDBODY and Clover Network are two apps that do this.
Use a Unary Protocol Thread to build this type of webhook integration. See the next section on Protocol Thread Triggers.
