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

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.
• 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

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 that event context.

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)