Webhooks

Overview

Webhooks allow your application to receive real-time HTTP POST notifications when events occur in Installer.com. Instead of polling the API for changes, you register a URL that receives event payloads as they happen.

Setting Up Webhooks

Register your endpoint

Go to Settings > Integrations > Webhooks in the Routing App and click Add Webhook.

Configure events

Select which events should trigger notifications to your endpoint.

Verify it works

Use the test button to send a sample payload to your endpoint.

Event Types

Order Events

Event	Description
`order.created`	A new order was created
`order.updated`	An order's details were updated
`order.completed`	An order was marked as completed
`order.cancelled`	An order was cancelled
`order.deleted`	An order was deleted
`order.dispatched`	An order was dispatched to a contractor
`order.assigned`	An order was assigned to a specific installer

Booking Events

Event	Description
`booking.created`	A new booking was scheduled
`booking.updated`	A booking was rescheduled or modified
`booking.cancelled`	A booking was cancelled

Workflow Events

Event	Description
`workflow.step.completed`	A workflow step was completed
`workflow.step.activated`	A workflow step became active

Webhook Payload

Each webhook delivery includes a JSON payload with event metadata and the relevant data:

{
  "event": "order.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organizationId": "router-uuid",
  "data": {
    "id": "order-uuid",
    "displayId": "P1-42",
    "name": "Solar Panel Installation",
    "status": 0,
    "customerName": "John Doe",
    "address": "123 Main St, Oslo",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Handling Webhooks

Your webhook endpoint should:

Return 2xx quickly — respond within 5 seconds to avoid timeouts
Process asynchronously — queue the event for background processing if it requires heavy work
Be idempotent — the same event may be delivered more than once

// Express.js example
app.post('/webhooks/installer', (req, res) => {
  const { event, data } = req.body;

  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookEvent(event, data);
});

Verifying Webhook Signatures

Webhook deliveries include a signature header to verify the request authenticity:

X-Webhook-Signature: sha256=<hex-encoded-hmac>

Verify the signature by computing an HMAC-SHA256 of the raw request body using your webhook secret:

import crypto from 'node:crypto';

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

Always verify webhook signatures in production to ensure requests come from Installer.com and haven't been tampered with.

Retry Policy

If your endpoint returns a non-2xx status code or times out, Installer.com retries the delivery:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the webhook delivery is marked as failed. You can view failed deliveries and manually retry them from the webhook settings page.

Troubleshooting

Issue	Solution
Not receiving events	Check that your endpoint is publicly accessible and returns 2xx
Duplicate events	Implement idempotency using the event ID
Signature mismatch	Ensure you're using the raw request body (not parsed JSON) for HMAC computation
Timeout errors	Return 200 immediately and process the event asynchronously

On this page