Webhooks

Overview

Webhooks in Installer.com are configured on individual workflow steps and fire when a step transitions to a specific state. Each webhook sends an HTTP request with a JSON payload that you define using Handlebars templates, allowing you to control exactly what data is sent to your external system.

How to configure a webhook

Handlebars syntax

Webhook payloads, URLs, and headers are rendered with the Handlebars templating language. JSON strings containing Handlebars expressions ({{ }}) are replaced with actual values at execution time.

Basic variable interpolation

Use {{variableName}} or {{object.property}} to insert values:

{
  "orderId": "{{order.id}}",
  "orderName": "{{order.name}}",
  "customerEmail": "{{order.email}}"
}

Nested access

Access deeply nested properties with dot notation:

{
  "installerName": "{{actor.primary-installer.organizationName}}",
  "installerEmail": "{{actor.primary-installer.organizationResponsibleEmail}}"
}

The unix helper

Use the unix helper to convert ISO date strings to Unix timestamps (seconds since epoch):

{
  "bookingStart": "{{unix booking.startAt}}",
  "bookingEnd": "{{unix booking.endAt}}"
}

Iterating over offer lines

Use the built-in {{#each}} helper to loop over arrays such as offer.lines. When building a JSON array, use {{#unless @last}},{{/unless}} to add commas between items but not after the last one:

{
  "orderId": "{{order.id}}",
  "lines": [
    {{#each latestOffer.lines}}
    {
      "name": "{{this.name}}",
      "quantity": "{{this.quantity}}",
      "unitAmount": "{{this.payerUnitAmount}}",
      "productId": "{{this.productId}}",
      "externalId": "{{this.externalId}}"
    }
    {{#unless @last}},{{/unless}}
    {{/each}}
  ]
}

Inside an {{#each}} block, this refers to the current item.

Full payload example

{
  "orderId": "{{order.id}}",
  "displayId": "{{order.displayId}}",
  "orderName": "{{order.name}}",
  "customerName": "{{order.contactPersonName}}",
  "customerEmail": "{{order.email}}",
  "customerPhone": "{{order.phoneNumber}}",
  "address": "{{order.address}}",
  "city": "{{order.city}}",
  "postalCode": "{{order.postalCode}}",
  "countryCode": "{{order.countryCode}}",
  "state": "{{state}}",
  "timestamp": "{{timestamp}}",
  "bookingStart": "{{unix booking.startAt}}",
  "bookingEnd": "{{unix booking.endAt}}",
  "installerOrg": "{{actor.primary-installer.organizationName}}",
  "installerContact": "{{actor.primary-installer.organizationResponsibleName}}",
  "offer": [
    {{#each latestOffer.lines}}
    {
      "name": "{{this.name}}",
      "quantity": "{{this.quantity}}",
      "unitAmount": "{{this.payerUnitAmount}}",
      "productId": "{{this.productId}}",
      "externalId": "{{this.externalId}}"
    }
    {{#unless @last}},{{/unless}}
    {{/each}}
  ]
}

Workflow states

A webhook is triggered when its step enters the configured state. The following states are available:

The state variable is automatically injected into the template context with the value of the triggering state.

Available variables

All variables below can be used in the URL, payload, and header templates. Variables are populated from the order and workflow data at the time the webhook fires.

Order

Workflow

Router (organization)

Responsible routing operator

Booking

Offer / Latest offer

offer is the offer connected to the current step's group. latestOffer is the most recently completed offer regardless of step group.

Each item in offer.lines:

Step

Actor (dictionary by slug)

Replace [slug] with the actor's slug from your workflow (e.g. primary-installer, inspector).

Actors (array)

The actors array contains all workflow actors with their full representative data:

Active step actor and representative

Custom fields

Custom fields are available in two formats:

By custom ID, for quick access to the field value:

By field UUID, for full field metadata:

State-dependent variable availability

Variables are populated based on which workflow steps have completed before the current step. If a required step has not yet been reached, the corresponding variables will be empty.

System variables

These variables are always available regardless of which step the webhook is configured on:

Retry policy

If your endpoint returns a non-2xx status code or the request fails, Installer.com retries the delivery up to 2 times (3 attempts total) with exponential backoff:

After 3 failed attempts, the webhook delivery is marked as failed. You can view the execution logs and status in the workflow step's notification history.

Handling webhooks

Your webhook endpoint should:

1. Return 2xx quickly: respond within 5 seconds to avoid timeouts
2. Process asynchronously: queue the event for background processing if it requires heavy work
3. Be idempotent: the same webhook may fire more than once (e.g. if a step transitions back to a previous state)

Troubleshooting