Webhooks

A webhook lets AssetGullak notify your own systems the moment something happens — a device goes offline, a policy violation opens, a bulk import finishes — instead of your integration having to repeatedly poll the API and ask “did anything change yet?” You register a URL and choose which events matter to you. From then on, whenever one of those events happens, AssetGullak sends an HTTP POST to your URL with the details — signed, so you can verify it genuinely came from AssetGullak and wasn’t sent by someone who found your endpoint.

Real-time

Delivered within seconds of the event happening — no polling delay.

Signed

Every payload carries an HMAC signature you can verify before trusting it.

Retried automatically

A failed delivery is retried on a backoff schedule, not dropped silently.

The envelope

Every webhook delivery is a POST request with the same outer shape, regardless of which event fired:

{
  "event_type": "device.offline",
  "created_at": "2026-08-17T10:30:00.000000+00:00",
  "company_id": "451ffb52-d823-4d79-86d6-23ab277cfd74",
  "data": {
    "...": "event-specific fields — see the reference below"
  }
}

Field	Description
`event_type`	Which event this is — see Event reference for the full list
`created_at`	When the event actually happened, in ISO 8601 (UTC). For events detected on a schedule (like a device going offline), this is when the underlying condition occurred, not when the check happened to run
`company_id`	Your company’s ID — useful if you route multiple AssetGullak accounts to the same receiving endpoint
`data`	The event-specific payload — shape differs per event type

Setting up a webhook

Create the webhook

POST /api/v1/webhooks with a URL and the event types you want to subscribe to:

{
  "name": "Slack alerts",
  "url": "https://your-receiving-endpoint.example.com/assetgullak",
  "event_types": ["device.offline", "policy_violation.opened"]
}

The response includes a secret — this is the only time you’ll ever see it. Store it securely; there’s no “reveal secret” option later, only delete and recreate.

Verify your endpoint can receive it

Trigger a matching event (or wait for a real one) and confirm a request actually arrives at your URL, with the headers described below.

Verify the signature

Before trusting the payload, recompute the signature yourself and compare it against the X-AssetGullak-Signature header — see Verifying signatures.

Webhooks are available on the Enterprise plan. Creating a webhook on a plan that doesn’t include this feature returns a 403.

Verifying signatures

Every delivery includes two headers:

Header	Value
`X-AssetGullak-Signature`	`sha256=<hex-encoded HMAC-SHA256 digest>`
`X-AssetGullak-Event`	The event type, same as the `event_type` field in the body

The signature is computed over the raw request body — the exact bytes sent, before any JSON parsing — using your webhook’s secret as the HMAC key. Recompute it the same way on your end and compare.

Compare signatures using a constant-time comparison function, not == or ===. A naive string comparison leaks timing information that can, in principle, let an attacker guess a valid signature byte by byte. Both examples below use the correct constant-time approach.

import hmac
import hashlib

def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    """raw_body must be the exact, unparsed request body bytes.
    signature_header is the full X-AssetGullak-Signature value,
    including the "sha256=" prefix."""
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require("crypto");

function verifySignature(secret, rawBody, signatureHeader) {
  // rawBody must be the exact, unparsed request body (Buffer or string).
  // signatureHeader is the full X-AssetGullak-Signature value, including
  // the "sha256=" prefix.
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(signatureHeader);

  // timingSafeEqual throws if the buffers differ in length, so check
  // that first rather than let a length mismatch throw an exception.
  if (expectedBuf.length !== receivedBuf.length) {
    return false;
  }
  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

Use the raw request body for verification — not a re-serialized version of the parsed JSON. Most web frameworks parse the body into an object before your handler runs; if you re-serialize that object to compute the signature, differences in key order or whitespace will produce a different signature than the one that was actually sent, and verification will fail even though the payload is genuine. Read the raw body first, verify, then parse.

Retries and delivery behavior

If your endpoint doesn’t respond with a 2xx status — or doesn’t respond at all within 10 seconds — the delivery is retried automatically:

Attempt	Delay before this attempt
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After the fifth attempt, the delivery is marked permanently failed and isn’t retried further. Your endpoint returning a 2xx at any point stops the retry sequence for that specific delivery. Each delivery attempt is logged and viewable via GET /api/v1/webhooks/{webhook_id}/deliveries — useful for diagnosing a missed event without needing to reproduce it live.

Event reference

Devices

device.online / device.offline

{
  "device_id": "uuid",
  "hostname": "DESKTOP-4F2KA",
  "status": "online",
  "last_seen": "2026-08-17T10:29:52Z",
  "assigned_location_id": "uuid | null",
  "assigned_location_name": "Gurgaon Office | null",
  "last_seen_location_id": "uuid | null",
  "last_seen_location_name": "Gurgaon Office | null"
}

device.warningSame shape as above, plus current resource usage:

{
  "device_id": "uuid",
  "hostname": "DESKTOP-4F2KA",
  "assigned_location_id": "uuid | null",
  "assigned_location_name": "Gurgaon Office | null",
  "last_seen_location_id": "uuid | null",
  "last_seen_location_name": "Gurgaon Office | null",
  "current_cpu_usage": 94.2,
  "current_ram_usage": 88.1,
  "current_disk_usage": 71.0
}

device.deleted

{
  "device_id": "uuid",
  "hostname": "DESKTOP-4F2KA"
}

The payload is self-sufficient since the device won’t exist to look up afterward.

Assets

asset.created

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "name": "MacBook Pro M4",
  "category": "Laptop"
}

asset.deleted

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "name": "MacBook Pro M4"
}

asset.status_changed

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "name": "MacBook Pro M4",
  "previous_status": "active",
  "new_status": "faulty"
}

asset.reassignedprevious_assignee / new_assignee are polymorphic — either can be an employee, department, or location. previous_assignee is null for a genuinely first-time assignment; new_assignee is null when an asset is unassigned entirely. expected_return_date is set only for temporary assignments — null for a normal, permanent one, and always null when the event represents an unassignment.

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "name": "MacBook Pro M4",
  "previous_assignee": { "type": "department", "id": "uuid", "name": "Engineering" },
  "new_assignee": { "type": "employee", "id": "uuid", "name": "Vineet Pandey" },
  "expected_return_date": "2026-10-01T00:00:00Z | null"
}

asset.device_linked / asset.device_unlinked

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "device_id": "uuid",
  "hostname": "Vineets-MacBook-Air.local"
}

asset.verifiedFired when IT staff directly marks an asset as physically verified — a standalone action distinct from the Physical Verification confirmation cycle (which is employee self-attestation via email). This event represents someone from IT personally confirming the asset in person.

{
  "asset_id": "uuid",
  "asset_tag": "AS-001",
  "name": "MacBook Pro M4",
  "verified_by": { "id": "uuid", "name": "Vineet Pandey" },
  "note": "Confirmed at Gurgaon office, serial matches | null"
}

Commands

command.completed / command.failedSame shape for both — exit_code carries the finer-grained success/failure signal. Full stdout/stderr aren’t included; fetch those via the API if you need them.

{
  "command_id": "uuid",
  "device_id": "uuid",
  "hostname": "DESKTOP-4F2KA",
  "command_type": "run_script",
  "exit_code": 0
}

command.expiredNo exit_code — the command never ran.

{
  "command_id": "uuid",
  "device_id": "uuid",
  "hostname": "DESKTOP-4F2KA",
  "command_type": "restart"
}

command_batch.completedOne summary event per batch, not one event per device.

{
  "batch_id": "uuid",
  "command_type": "update_agent",
  "total_devices": 50,
  "succeeded_count": 47,
  "failed_count": 3
}

Bulk import

bulk_import.completed

{
  "job_id": "uuid",
  "entity_label": "Assets",
  "original_filename": "gurgaon-office-devices.csv",
  "created_rows": 42,
  "updated_rows": 8,
  "invalid_rows": 3
}

Policy violations

subject is polymorphic — a violation can be about a device or an asset.policy_violation.opened / policy_violation.resolved

{
  "violation_id": "uuid",
  "policy_id": "uuid",
  "policy_name": "Disk Space Policy",
  "policy_type": "disk_usage",
  "subject": { "type": "device", "id": "uuid", "name": "DESKTOP-4F2KA" },
  "current_value": "97%"
}

policy_violation.acknowledgedSame as above, plus who acknowledged it:

{
  "violation_id": "uuid",
  "policy_id": "uuid",
  "policy_name": "Disk Space Policy",
  "policy_type": "disk_usage",
  "subject": { "type": "device", "id": "uuid", "name": "DESKTOP-4F2KA" },
  "current_value": "97%",
  "acknowledged_by": { "id": "uuid", "name": "Vineet Pandey" }
}

policy_violation.unacknowledgedSame shape as policy_violation.opened — acknowledged_by is no longer relevant once cleared.policy_violation.assigned

{
  "violation_id": "uuid",
  "policy_id": "uuid",
  "policy_name": "Disk Space Policy",
  "policy_type": "disk_usage",
  "subject": { "type": "device", "id": "uuid", "name": "DESKTOP-4F2KA" },
  "current_value": "97%",
  "assigned_to": { "id": "uuid", "name": "Priya Sharma" }
}

policy_violation.unassignedSame shape as policy_violation.opened — no assigned_to field, since there’s no assignee left to describe.policy_violation.fix_attemptedFired when someone claims they’ve addressed a violation — this is not the same as resolution. Resolution is always verified automatically by the policy engine on its next evaluation pass, never claimed directly by a person; this event just marks that someone believes they’ve fixed it and the system should double check. If the claim turns out to be right, a policy_violation.resolved event follows once the policy engine confirms it; if not, the violation simply stays open.

{
  "violation_id": "uuid",
  "policy_id": "uuid",
  "policy_name": "Disk Space Policy",
  "policy_type": "disk_usage",
  "subject": { "type": "device", "id": "uuid", "name": "DESKTOP-4F2KA" },
  "current_value": "97%",
  "claimed_by": { "id": "uuid", "name": "Priya Sharma" }
}

Managing webhooks

Action	Endpoint
Create a webhook	`POST /api/v1/webhooks`
List your webhooks	`GET /api/v1/webhooks`
Get one webhook	`GET /api/v1/webhooks/{id}`
Update a webhook	`PATCH /api/v1/webhooks/{id}`
Delete a webhook	`DELETE /api/v1/webhooks/{id}`
View delivery history	`GET /api/v1/webhooks/{id}/deliveries`

A company can have up to 10 webhooks active at once. Creating or managing webhooks requires an Owner or Admin role.

Webhook URLs must resolve to a genuine public address. URLs pointing at localhost, private IP ranges, or other internal/reserved addresses are rejected at creation and update time.

Locations — assigned_location and last_seen_location in device event payloads both reference locations
Location signals — how last_seen_location gets populated automatically

Getting Started

Core Concepts

Organisation

Features

Agent Reference

Real-time

Signed

Retried automatically

The envelope

Setting up a webhook

Verifying signatures

Retries and delivery behavior

Event reference

Managing webhooks

Real-time

Signed

Retried automatically

​The envelope

​Setting up a webhook

​Verifying signatures

​Retries and delivery behavior

​Event reference

​Managing webhooks

​Related

The envelope

Setting up a webhook

Verifying signatures

Retries and delivery behavior

Event reference

Managing webhooks

Related