Skip to content
Installer.com logo

Configure webhooks

A webhook posts order data to an external system when a workflow step reaches a state. You set one up as a notification on a workflow, next to email and SMS.

Add a webhook to a workflow

  1. Select Workflows in the sidebar.
  2. Open the workflow you want. A published version is read-only, so select Start editing to create a draft, or Go to draft if a draft already exists.
  3. Open the Notifications tab.
  4. Select Add.
  5. Enter a Name for the notification.
  6. Set Type to Webhook.
  7. Choose the Step the webhook belongs to.
  8. Select the States that trigger it. The list shows only the states that step can reach.
  9. Choose When the webhook fires.
  10. Fill in Webhook URL template, Webhook payload template and Webhook headers template.
  11. Select Save, then Publish to put the draft live.

There is no recipient to pick. A webhook goes to the URL in the template, not to a person.

When options

Option Behavior
On state Fires as the step enters the state.
After state Fires a number of Days after the state is registered.
Before state Fires ahead of the state. Available only when the step has a deadline and Overdue is selected.

Write the templates

All three templates use Handlebars. The URL is sent as a POST with a JSON body and Content-Type: application/json, unless your headers template overrides the header.

Select This text can be templated next to any of the three fields to see the variables the product documents.

Variable What it holds
state The step state that triggered the notification.
order The order: id, name, email, phoneNumber, address, city, postalCode, countryCode, source.
offers Every accepted offer, each with its lines.
allOfferLines Every offer line across those offers, flattened into one list.
booking The booking linked to the step.
customFields.<id> One custom field value, by its field reference key.
workflow The workflow, including eventData from background events.
step The step the notification belongs to.
actor.<slug> The organization and responsible person behind a workflow actor.
timestamp When the webhook was built.

String values are JSON-escaped for you, so quotes, backslashes and newlines in an address or a note stay valid JSON. Numbers and booleans render unquoted.

Use {{#each}} to list offer lines. Handlebars writes no separator of its own, so add the comma yourself:

{
  "orderId": "{{order.id}}",
  "orderName": "{{order.name}}",
  "lines": [
    {{#each allOfferLines}}
    {
      "name": "{{this.name}}",
      "quantity": {{this.quantity}},
      "externalId": "{{this.externalId}}"
    }{{#unless @last}},{{/unless}}
    {{/each}}
  ]
}

Two helpers are available beyond the Handlebars built-ins:

Helper Result
{{index1}} The position inside an {{#each}} block, counting from 1.
{{unix date}} A date as a Unix timestamp in seconds.

actor.<slug>.organizationExternalId carries an actor organization’s external ID. It is filled in only when that organization sits inside your own organization hierarchy. For any other organization it is empty, so an unrelated contractor’s external ID never reaches your receiver.

Delivery outcomes

The response code from your URL decides the outcome.

Response Outcome
2xx Success.
5xx Retried, up to three attempts, with a growing delay between them. Failed after the third.
Any other non-2xx, including 4xx Failed immediately. A rejected request is a configuration problem, and repeating it does not fix one.

A request that never gets a response, because the host is unreachable, is retried on the same three-attempt rule.

When a webhook fails

Open the order and check the Notifications panel. Each attempt is listed with its status and its log.

Failures across all orders surface on the Workflows page as a notifications failed last week alert. Select View to open the list, then open one notification to read the payload that was sent and the response that came back. Select Retry to send it again with the last saved payload.

If the URL template refers to a variable that has no value, the notification fails before any request goes out. An empty Webhook URL template fails the same way: nothing stops you saving it, and every send then fails.

Need help? Contact Installer.com support.

Was this helpful?