Skip to content

Webhooks

Register outbound HTTP endpoints that receive platform events in real time. Use them to integrate the platform with your CMMS, BI pipeline, Slack / Teams, or custom systems.

Required role

Admin.

Overview

A webhook is a URL the platform calls when a specific event happens in your tenant. Webhook endpoints live in your infrastructure (or a third-party integration platform); the platform sends JSON payloads to them.

Typical use cases:

  • Post completed tasks to your existing CMMS / Maximo / SAP-PM.
  • Alert Slack or Microsoft Teams when a Critical repair request is filed.
  • Feed a data warehouse with shutdown events for longer-term analytics.
  • Trigger a Zapier / Make workflow to route repair requests into a ticketing tool.

Open the Webhooks page

Configuration → Webhooks.

You see the list of webhooks configured for your company:

Column Meaning
Name Your label.
URL The endpoint the platform calls.
Events Which event types trigger this webhook.
Last fired When this webhook was last called.
Success rate 24-hour rolling success rate (2xx responses / total attempts).
Active On / off toggle.

Register a webhook

  1. New webhook.

  2. Fill in:

    Field Notes
    Name Human label. "Slack #maintenance" or "SAP-PM bridge".
    URL The endpoint. Must be HTTPS in production.
    Events Multi-select from the available event types (see below).
    Secret (optional) A shared secret used to sign each request with HMAC-SHA256 (header: X-SMTM-Signature).
    Headers (optional) Additional headers to send with every request (e.g. Authorization: Bearer xyz).
    Description Internal documentation of what this webhook does.

  3. Save. The webhook is active immediately for new events.

Event types

Common event categories the platform emits:

  • task.assigned — a task is assigned to a technician.
  • task.completed — technician submitted a task.
  • task.approved / task.rejected — Supervisor action.
  • repair_request.created — a new repair request.
  • repair_request.updated — status change.
  • shutdown.reported — new shutdown.
  • shutdown.resolved — shutdown closed.
  • user.created / user.deactivated — account changes.
  • audit.exported — someone exported the activity log.

Not every installation exposes every event; the Events dropdown on the webhook form lists what's available on yours.

Payload format

Every webhook POST includes:

{
  "event": "task.completed",
  "timestamp": "2026-04-24T09:15:30+07:00",
  "company_id": 1,
  "company_name": "PT Kahatex",
  "data": {
    "task_id": 12345,
    "asset_id": 678,
    "technician_id": 42,
    ...
  }
}

Headers:

  • Content-Type: application/json
  • User-Agent: SmartMaintenance/1.0
  • X-SMTM-Event: task.completed
  • X-SMTM-Delivery: <uuid> — idempotency key.
  • X-SMTM-Signature: sha256=<hex> — HMAC signature, if you configured a secret.

Verify signatures

If you configured a secret:

  1. Take the raw request body as bytes.
  2. Compute HMAC-SHA256(body, secret).
  3. Compare to the hex value in X-SMTM-Signature (after the sha256= prefix).
  4. Use a constant-time comparison (not ==) to prevent timing attacks.

If signatures don't match, reject the request — it may be spoofed.

Delivery and retries

  • First attempt — immediate when the event fires.
  • Retry on non-2xx — exponential backoff at 1, 5, 25, 125, 625 seconds (5 retries, ~15 minutes total).
  • After 5 failed retries — the event is marked permanently failed and logged. Not retried further.

The webhook's detail page shows failed-delivery history and lets you manually re-fire.

Test-fire

Before activating a webhook in production:

  1. Webhooks → (row) → Send test event.
  2. Pick an event type.
  3. The platform sends a test payload (with a synthetic data block) to your URL.
  4. Check your endpoint logs; if you get 200 back, it's wired up.

Test events are flagged in the payload with "test": true so your endpoint can distinguish them.

Disable or delete

  • Disable — toggles off. No new events fire this webhook. Reversible.
  • Delete — removes the webhook permanently. History is retained in the audit log.

Things to watch for

HTTPS only for production

Payloads may contain identifying data (user names, task details). Don't send them over HTTP. The platform warns when you register a non-HTTPS URL.

Use a shared secret

Signing with a secret is 5 minutes of setup and prevents spoofed events from landing in your downstream system. Always use one.

Webhooks are not guaranteed in-order

Two events fired close together may arrive in either order. Your endpoint should use the timestamp field to order them if that matters.

Troubleshooting

Problem Fix
Webhook never fires Confirm Active toggle; confirm the event type is in your selection
Signature check fails Make sure you're hashing the raw body (bytes), not the parsed JSON
Failed deliveries accumulating Check your endpoint is reachable, returns 2xx, and responds under 30 seconds
Duplicates arriving Use X-SMTM-Delivery as idempotency key — the platform may retry on transient failures