Webhooks

OverviewCopy Anchor Link

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 webhookCopy Anchor Link

Handlebars syntaxCopy Anchor Link

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 interpolationCopy Anchor Link

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

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

Nested accessCopy Anchor Link

Access deeply nested properties with dot notation:

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

The unix helperCopy Anchor Link

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 linesCopy Anchor Link

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 exampleCopy Anchor Link

{
  "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 statesCopy Anchor Link

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 variablesCopy Anchor Link

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.

OrderCopy Anchor Link

WorkflowCopy Anchor Link

Router (organization)Copy Anchor Link

Responsible routing operatorCopy Anchor Link

BookingCopy Anchor Link

Offer / Latest offerCopy Anchor Link

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:

StepCopy Anchor Link

Actor (dictionary by slug)Copy Anchor Link

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

Actors (array)Copy Anchor Link

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

Active step actor and representativeCopy Anchor Link

Custom fieldsCopy Anchor Link

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 availabilityCopy Anchor Link

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.

TriggerCopy Anchor Link

What the trigger itself was about, resolved into names rather than ids. Keys are absent when the trigger does not carry them, so {{#if trigger.tag}} tells you whether a tag was involved.

The {{ picker in the builder offers the subset that is specific to the trigger you chose; the rest of the table is reachable by typing it.

System variablesCopy Anchor Link

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

Retry policy (step webhooks)Copy Anchor Link

This section describes webhooks configured on a workflow step. An automation webhook retries on its own schedule and is covered under Webhooks from automations.

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 delivery is marked as failed. You can view the execution logs and status in the workflow step's notification history.

Webhooks from automationsCopy Anchor Link

An automation can also send a webhook. It shares the templating and variables described above, and adds the guarantees below. Both kinds may be enabled at once.

RetriesCopy Anchor Link

An automation webhook backs off on its own schedule (roughly 30 seconds, then 2 minutes, then 8 minutes, then every 25 minutes) up to the automation's attempt limit, and honours Retry-After when you send one. A receiver that fails repeatedly has its endpoint paused for a few minutes rather than being hammered; deliveries queue and resume.

Signed requestsCopy Anchor Link

Every request is signed following the Standard Webhooks specification, so you can verify it with the standard library for your language rather than implementing ours.

The signed string is {webhook-id}.{webhook-timestamp}.{raw request body}, and the signature is HMAC-SHA256 of that string using the endpoint's signing secret. The secret is shown once when the endpoint is created and again when it is rotated.

We also send, always and never absent:

One more is sent whenever the message has a trigger, which is every webhook an automation sends:

A header you set yourself is dropped if it uses one of these names. We always send our own value, so yours would have been overwritten anyway.

Authenticating to your endpointCopy Anchor Link

The signature above proves a request came from us. If your endpoint also requires a credential from us, an operator can attach one to the endpoint. Both options are set on the endpoint, not on the automation, so rotating them needs no republish and takes effect on a delivery already queued for retry.

A static header. Any header your API expects, for example X-Api-Key: <key>. Values are write-only: once saved they are never returned by the API, and only their names are shown.

OAuth2 client_credentials. We exchange a client id and secret for a bearer token before the delivery and send it as Authorization: Bearer <token>. Tokens are cached until shortly before they expire, so a burst of deliveries is one grant rather than one per request.

Credentials live on the endpoint, so every automation sending to that host uses them without repeating the configuration. If we get a 401 from your endpoint we discard the cached token, so the next attempt uses a fresh one.

Two failure modes are worth knowing about, because they look different in the delivery log: a failed token exchange never reaches your endpoint and is recorded against the token step, so a provider outage does not read as your endpoint rejecting us. A rejected grant (invalid_client, invalid_scope) is not retried, because resending the same credentials cannot succeed.

Choosing a methodCopy Anchor Link

An automation webhook sends POST unless you pick otherwise. PUT, PATCH and DELETE carry the body you write; GET sends no body at all, and no Content-Type header with it. The method is frozen on the message alongside the rendered bytes, so a retry repeats the verb it first sent.

Authoring against real dataCopy Anchor Link

The builder renders the request before you publish it. Typing {{ in the address, a header value or the body lists what this trigger and workflow actually populate, and Show preview renders the whole request (address, headers and body) without sending anything.

Once a webhook is saved you can also run it against one real order from Run automation on…. A webhook may be rehearsed while it is still a draft.

A run started this way has no triggering event, so state and the trigger-specific trigger.* variables are empty. A path that uses one fails on a manual run even when the preview renders it.

Changes to existing behaviourCopy Anchor Link

A webhook already published keeps sending what it sent before. Its step, booking, offer and representative are picked the way they always were.

The next time you publish it, it picks them from what triggered the run instead. Check these before republishing:

A path such as /steps/{{step.id}} on a dispatch trigger posts to a different step after republishing. On an order with one booking and one active step, nothing changes.

Still only on workflow-step webhooksCopy Anchor Link

These have no equivalent on an automation webhook yet, so a step webhook using one cannot move across:

What to rely onCopy Anchor Link

1. Delivery is at-least-once. Dedupe on webhook-id: the same message may arrive more than once, and every copy carries identical bytes.
2. Ordering is not guaranteed. Retries and independent automations interleave, so order on your own payload timestamps rather than on arrival.
3. Two events can describe one fact, so also key on the subject id and event type, not only on webhook-id.
4. Reject a stale timestamp. Five minutes of tolerance is a reasonable window; never accept 0.
5. We may add fields. Ignore unknown ones. Removing or renaming a field gets a new event type rather than a silent change.
6. A manual resend carries a new webhook-id and does not cancel retries that are already pending.

Responses we act onCopy Anchor Link

The request times out after 10 seconds by default, configurable per endpoint up to 30. Only https is accepted, and literal private or link-local addresses are refused.

Handling webhooksCopy Anchor Link

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)

TroubleshootingCopy Anchor Link