Docs
← Back to Docs
Last updated: 2026-07-01

Webhooks

Webhooks let InvyMate push events to your system automatically, instead of your integration polling APIs.

For endpoint-level details, including filters and replay routes, see API Endpoints (Overview).

Plan availability

  • Webhooks are available in the Pro plan.
  • During active trial, this feature is available.

Where to configure

  • Go to Configuration → Webhooks.
  • Create one or more endpoints.

Quick start:

  1. Create endpoint and choose events.
  2. Save secret (shown once only).
  3. Click Verify and ensure your receiver returns 2xx.
  4. Trigger a real event (create/update asset/person).
  5. Check Deliveries tab and replay failed items if needed.

Each endpoint contains:

  • Name
  • Destination URL (https://...)
  • Subscribed event types
  • Active/inactive state
  • Verification status

The create/edit form validates URL format and requires at least one subscribed event before submission, so invalid form input stays inline instead of surfacing raw system error payloads.

Events in v1

Current lifecycle events:

  • asset.created
  • asset.status.changed
  • asset.location.changed
  • asset.assigned
  • asset.unassigned
  • person.created
  • person.updated

Delivery behavior

  • Delivery is asynchronous (eventual, usually within minutes).
  • Ordering is best-effort.
  • Retry policy: 3 total attempts within 24 hours.
  • Failed deliveries stay in logs and can be replayed.
  • Replay actions use the same async delivery queue as normal webhook processing, so a manual replay can recover after a transient queue-side issue.
  • No historical backfill on endpoint create: only events emitted after creation are delivered.

Security and signatures

Each endpoint has a secret.

  • You can provide a custom secret on create, or InvyMate generates one.
  • Generated secret is shown once in UI.

Each delivery includes signature headers:

  • X-InvyMate-Signature
  • X-InvyMate-Signature-Timestamp
  • X-InvyMate-Delivery-Id
  • X-InvyMate-Event-Id
  • X-InvyMate-Event-Type

Signature format uses HMAC SHA-256:

  • Header value: t=<unix_timestamp>,v1=<hex_digest>
  • Signed message: <timestamp>.<raw_body>

Idempotency (receiver-side)

Webhook delivery is at-least-once, so receivers must deduplicate.

Recommended key:

  • X-InvyMate-Delivery-Id

Minimal receiver flow:

  1. Read X-InvyMate-Delivery-Id.
  2. If ID already processed, return 200 and skip side effects.
  3. Verify X-InvyMate-Signature.
  4. Process event and persist delivery ID as processed.

Example (Node/Express pseudo-code):

const deliveryId = req.header('X-InvyMate-Delivery-Id');
if (!deliveryId) return res.status(400).send('missing delivery id');
if (await alreadyProcessed(deliveryId)) return res.status(200).send('duplicate');
verifySignature(req); // throws on invalid
await handleEvent(req.body);
await markProcessed(deliveryId);
return res.status(200).send('ok');

Verification flow

  • Use Verify action on endpoint.
  • InvyMate sends a verification event (webhook.endpoint.verification).
  • Your receiver must return 2xx and echo the challenge from payload data.challenge.
  • Accepted verification responses:
    • JSON: { "challenge": "<exact challenge value>" }
    • Plain text body: <exact challenge value>
  • Endpoint status is updated based on challenge-matched delivery result.

Operations UI

The Deliveries tab provides:

  • Filter by endpoint and status
  • Attempt count and response code
  • Delivery detail view (error, response snippet, payload)
  • Replay single delivery
  • Replay entire event

Attempt counts are displayed as attempts used out of the total allowed attempts.

  • 1 of 3 means the first attempt is in progress or completed.
  • 2 of 3 means two attempts have already run and one retry remains.
  • 3 of 3 means the final attempt already ran; no retries remain.

Replay actions explained

There are two replay actions and they solve different problems:

  • Replay delivery = retry one specific failed delivery row (one endpoint + one event).
  • Replay event = re-run the source event flow and enqueue fresh delivery attempts for every endpoint subscribed to that event.

Practical example:

  1. Asset status changes to retired.
  2. Endpoint A fails, endpoint B succeeds.
  3. If only endpoint A failed, use Replay delivery on endpoint A row.
  4. If receiver logic/outage affected broader processing and you want to re-run event handling, use Replay event.

Health and escalations

  • GET /api/v1/webhooks/health returns delivery health counters for a time window.
  • Optional query: windowMinutes (5..1440), default 60.
  • Summary includes success rate, failed/dead counts, retry depth, and top failing endpoints.

Sustained failure automation:

  • InvyMate evaluates webhook health every 15 minutes.
  • Escalation triggers when:
    • any dead deliveries exist in the last 15 minutes, or
    • success rate is below 95% with at least 10 deliveries in the window.
  • Escalation is sent as in-app notification to configured escalation recipients.

Incident runbook (v1)

When webhook delivery degrades:

  1. Open Configuration → Webhooks → Deliveries.
  2. Filter by failed / dead and inspect response codes + snippets.
  3. Verify receiver availability and signature validation.
  4. Fix receiver endpoint (or credentials/allowlist).
  5. Replay failed delivery or replay full event.

Deployment checks:

  • Confirm your endpoint is reachable from the public internet.
  • Confirm your endpoint returns 2xx and verifies signatures correctly.

Known limitations (v1)

  • No per-endpoint custom retry policy
  • No strict global ordering guarantee
  • No batch replay workflow (single actions only)
← API Endpoints (Overview)Plans & Pricing (Overview) →