Overview
With the webhook trigger, any external system can start a Formalize workflow. Monitoring services, security scanners, ticketing systems and chat apps send their events straight to Formalize, which starts the right workflow automatically and brings all your processes together on one platform.
Why use webhooks in Formalize
Real-time automation. Formalize starts a workflow as soon as an event happens. For example, an alert from a monitoring tool creates an incident right away, with no manual copy-paste.
Open to almost any system. The webhook trigger accepts events from any tool that can send an HTTP request: SaaS tools, cloud platforms, internal applications or custom scripts. No dedicated integration is needed for each one.
One central platform. Formalize brings events from all these tools together and handles them with the same records, owners and processes. Teams work in one place instead of switching between multiple systems.
Two-way connections. Webhooks bring events into Formalize. To send data back, add an Action node to the workflow and select the Create HTTP request action, which sends a request to an external system's REST API. Together, the webhook trigger and the Create HTTP request action let you build a two-way connector with your existing technical stack.
Before you start
To create webhook workflows in Formalize, you need:
The Automations feature enabled for your company. Access rights alone don't turn it on. To enable it, contact your Formalize account manager, or Formalize support if you don't have one.
A company account that isn't a trial account. The webhook trigger isn't available on trial accounts.
Automations access rights, which control access to Operations > Workflows (see Access Roles Management). Go to Settings > Users & Access > Access Roles, click Edit next to the role, expand Automations by clicking the arrow (>), select the following permissions, then click Save:
Automations sidebar to show Workflows in the navigation.
View automations to open workflows.
Add/Edit/Delete automations as needed to manage workflows.
An external system that can send HTTP POST requests to a URL.
Create a webhook workflow
Webhooks are configured in Operations > Workflows. Each Formalize webhook workflow has its own webhook URL. When an external system sends an event to the webhook URL, the workflow runs, and the content of the event is available as variables in every step. For general workflow building, such as stages, conditions and the Runs tab, see Workflow Builder.
Save the workflow once to generate its webhook URL. You can finish building the workflow later.
Go to Operations > Workflows and click + Add Workflow.
Select Build from Scratch.
Enter a name for the workflow.
Set Workflow Status to Enabled. Formalize rejects events sent to a disabled workflow.
Click Builder to open the canvas.
Click the Trigger node and select Webhook.
Click + below the trigger and select Action.
Enter a name for the step.
Click Select action > Communication and choose Run code from the dropdown. You don't need to configure it: a workflow needs at least one action before you can save it.
Click Create to save the workflow.
Open the Trigger node again and click Copy to copy the webhook URL.
💡 Before you paste the webhook URL: some external systems check the URL as soon as you paste it. If yours does, set up a verification rule first. See Verify and secure webhooks in Formalize workflows.
In the external system's webhook settings, paste the webhook URL.
The webhook URL has this format:
https://api.formalize.com/api/public/workflows/<workflow UID>/webhook/<webhook UID>
Send a test event
Send a test event to check that Formalize receives it. You can either:
Make the external system send an event, for example by creating a test alert in your monitoring tool.
Send an event yourself with this command. Replace <your webhook URL> with the URL you copied:
curl -X POST "<your webhook URL>" \
-H "Content-Type: application/json" \
-d '{"alert": {"id": "alert-123", "severity": "high", "message": "Test alert"}}'
Then copy the content of the event, called the payload:
Open the workflow and go to the Inbound events tab.
Find the event you just sent (the newest row) and click Payload.
In the Body box, click the copy icon.
You'll paste this payload in Create trigger variables.
Create trigger variables
Trigger variables turn fields from the payload into named variables that you can use in later steps. Formalize reads a sample payload to see which fields the event contains, and creates the variables for you.
Click the Trigger node.
Paste the payload into the Sample payload box.
Click Derive variables.
Rename the variables, change their type, or remove the ones you don't need.
Click Save to save the trigger variables.
To add a variable yourself, click Add variable. If you click Derive variables again later, Formalize only adds new fields and keeps your existing variables.
The following table describes the four settings of each trigger variable:
Setting | What it controls |
Name | How the variable appears in later steps. By default, the name comes from the path: alert.severity becomes alertSeverity. |
Source | Where the value comes from: the body, a header, or a query parameter. |
Type | Text, Number, Boolean or Date. Header and query parameter values are always Text. |
Path | The field to read, in dot notation. For example, alert.severity reads the severity field inside alert. |
💡 Note: Paths are case-sensitive. If an event doesn't contain a field, the event is still accepted, the run continues, and the variable is empty.
Use webhook data in your workflow
Trigger variables appear in the variable picker of every step after the trigger:
Conditions: for example, continue only if alertSeverity equals high.
Action inputs: for example, use alertMessage as the title of an incident.
Transform data with Run code
To reshape a value before you use it, add an Action node and select Run code (Select action > Communication > Run code). Run code runs JavaScript. In your code, context.trigger is an object that holds your trigger variables, for example context.trigger.alertSeverity. Each key in the object you return becomes a variable in later steps.
For example, this code creates a variable named incidentTitle from two trigger variables:
return {
incidentTitle: `[${context.trigger.alertSeverity}] ${context.trigger.alertMessage}`
};Later steps can use incidentTitle like any other variable, for example as the title of a Create incident action.
Check inbound events
The Inbound events tab lists the events the workflow received, newest first. It also lists events that didn't start a run.
Each event has one of six statuses. The normal path is Received → Processing → Processed. Rejected events don't start the workflow. If both rejection conditions apply, Rejected · IP takes precedence.
Status | When it occurs |
Received | The webhook was accepted and is waiting to be picked up for processing. |
Processing | The event has been picked up and queued for processing. This doesn't necessarily mean the workflow actions are running yet. |
Processed | The event finished processing without an unhandled error. This doesn't guarantee that the workflow itself succeeded: click View run to check its result. |
Failed | An unhandled error occurred while processing the inbound event. This is separate from a failed workflow run. |
Rejected · IP | The sender's IP address didn't match the workflow's IP allowlist. |
Rejected · disabled | The workflow was disabled when the webhook arrived. |
To see what an event contained, click Payload on its row. You'll see its body, headers and query parameters.
To see the run an event started, click View run. The run details show the run status, the payload that started it, and the result of each step.
A failed event and a failed run are different. An event has the status Failed when Formalize can't process it or start the workflow. A run fails when the workflow starts but a step errors, for example an action has invalid inputs, a Create HTTP request action fails, or a Run code action errors. An event with the status Processed can still start a run that fails, so click View run to check which step failed.
💡 Note: Some external systems resend an event if they time out, or send the same event more than once. Each event starts its own run, so make sure your workflow's actions are safe to repeat, for example by checking for an existing incident before you create one.
Troubleshooting
An event has the status Rejected
Rejected events don't start the workflow. The status shows why:
Rejected · disabled: the workflow was disabled when the event arrived. Set Workflow Status to Enabled, then send the event again.
Rejected · IP: the sender's IP address isn't in the workflow's IP allowlist. Add it to the allowlist, then send the event again. See Verify and secure webhooks in Formalize workflows.
The external system reports a 404 error
The URL in the external system is wrong or out of date. Copy the URL again from the Trigger node and update it in the external system. Events sent to a wrong URL don't appear in the Inbound events tab.
Trial accounts can't receive webhook events and also get a 404 error.
A trigger variable is empty
The event didn't contain a field at the variable's path. In the Inbound events tab, click Payload on the event and compare its body with the variable's Path and Source. Paths are case-sensitive.
Verify and secure your Formalize webhook
Until you secure your webhook, anyone who has its URL can send events that start the workflow. Share the URL only with the external system, and don’t post it in tickets or chats.
Verify and secure webhooks in Formalize workflows explains how to:
Verify your webhook URL: answer the challenge request that some external systems send before they send events.
Filter out test events: stop runs started by test events, such as GitHub pings.
Check a shared secret: make your workflow act only on events that contain your secret.
Restrict senders: accept events only from specific IP addresses with an IP allowlist.