# Webhooks

> Push AssetLab events to your other systems the moment they happen - no polling, no batch lag.

Source: https://app.assetlab.ca/docs/manage/webhooks

Webhooks turn AssetLab from a system you ask into a system that tells you: when something happens - a work order is created, an asset changes - AssetLab POSTs a JSON payload to an HTTPS endpoint you control.

> [!note] Webhooks are available on the Enterprise plan (or with the API keys add-on), alongside [API keys](/docs/manage/api-keys).

## When to use webhooks vs. the API

| You want to… | Use |
|---|---|
| React the moment something happens | **Webhooks** |
| Query or change data on your schedule | [REST API](/docs/reference/rest-api) |
| Sync a BI warehouse nightly | API (webhooks as a freshness signal, optionally) |
| Post events into Microsoft Teams | The native **Settings → Integrations** Teams relay - no custom receiver needed |

## Available events

Eight events across three resources - subscribe to exactly the ones you need:

| Resource | Events |
|---|---|
| Work orders | `work_order.created`, `work_order.updated`, `work_order.deleted` |
| Assets | `asset.created`, `asset.updated`, `asset.deleted` |
| Work requests | `work_request.created`, `work_request.updated` |

## Setting up

**Settings → Webhooks** (Administrator):

1. **Endpoint URL** - HTTPS only.
2. **Events** - pick from the list above. Subscribe narrowly; you can widen later.
3. **Secret** - each webhook has a signing secret, shown once at creation. Every delivery is signed so your receiver can verify the payload came from AssetLab.

A **Send test** button on each subscription fires a test delivery - wire your receiver, test, then go live.

## The delivery contract

- Each POST carries an **HMAC-SHA256 signature** of the body in the `X-AssetLab-Signature` header, plus `X-AssetLab-Event` (the event type) and `X-AssetLab-Delivery` (a unique delivery ID).
- Your endpoint has **10 seconds** to respond with a 2xx.
- Failed deliveries are retried up to **5 attempts**, backing off at 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours.
- After **10 consecutive failures** the subscription is automatically disabled; the webhook screen warns you from the 5th failure on.

## Receiving deliveries

Your endpoint should:

- **Verify the signature** before trusting anything.
- **Respond 2xx quickly** - acknowledge first, process async. Slow receivers hit the 10s timeout and trigger retries.
- **Tolerate retries.** Design your handler idempotently - the event carries the record ID; upsert, don't blind-insert.
- **Not assume order.** Two rapid updates may arrive out of order; treat each delivery as "go look at the record", or use the payload's timestamps.

## Common wirings

- **Chat visibility** - work order events → a channel your on-call watches (for Teams, use the native **Settings → Integrations** relay instead of building a receiver).
- **Ticketing sync** - work request events → your service desk's intake queue.
- **Escalation logic** - `work_request.created` → your rules engine decides who gets paged.

> [!tip] No receiver infrastructure? A low-code automation platform (or a small serverless function) receiving the webhook is a one-afternoon build - the signature-verify + respond-fast + idempotent pattern above still applies.

## Debugging

The webhook screen shows recent deliveries and their outcomes - status codes, timestamps, retry attempts. "Did AssetLab send it or did we drop it?" is answered there before anyone greps a server log.