Webhooks & API — Zentra ITSM Docs

Programmatic access today

Zentra is currently a single-tenant deployment whose HTTP endpoints are session-authenticated and serve the agent UI. There is no public, token-authenticated REST API yet. For programmatic integration today, use:

Outbound webhooks — Zentra POSTs signed payloads to your URLs when configured events happen.
Inbound webhooks — your systems POST to Zentra to create or update records (today: inbound email; future: any custom intake).
The workflow engine — actions inside a workflow can call any HTTP URL to push data to your other tools.

A public REST API with token auth, versioning, and pagination is tracked. If you have a use case for it during evaluation, tell us — customer asks help us prioritize.

Outbound webhooks

Configure subscriptions under Settings → Integrations → Outbound webhooks. Each subscription has:

Target URL — where the payload is POSTed.
Event filter — one or more event types from the catalog below.
Signing secret — used by Zentra to HMAC-sign each payload.
Retry policy — bounded retries with exponential backoff on non-2xx responses.
Delivery log — last N deliveries with status code, timing, and response body for diagnostics.

Event catalog

Subscribe to any combination of:

ticket.created
ticket.updated
ticket.status_changed
ticket.resolved
ticket.sla_breached
change.created
change.approved
change.rejected
change.completed
problem.created
problem.resolved
asset.created
asset.lifecycle_changed

The full and current event list is shown in the dropdown when creating a subscription.

Payload shape

Every payload is JSON. Top-level fields are stable across event types; the data field’s shape depends on the event.

{
  "event":      "ticket.created",
  "delivery_id":"01HYZ8M3PA...",
  "ts":         "2026-05-05T11:45:07Z",
  "data": {
    "id":       "tkt_01HYZ8N3PA...",
    "key":      "INC-4821",
    "subject":  "Cannot connect to VPN",
    "type":     "incident",
    "status":   "open",
    "priority": "high",
    "category": "Network",
    "team_id":  null,
    "requester_email": "[email protected]",
    "created_at": "2026-05-05T11:45:07Z"
  }
}

Request headers

POST /your-endpoint
Content-Type: application/json
X-Zentra-Event: ticket.created
X-Zentra-Delivery-Id: 01HYZ8M3PA...
X-Zentra-Signature: 7f2d4e9b8c...

X-Zentra-Event — event type, identical to the event filter.
X-Zentra-Delivery-Id — unique per delivery attempt; use it for idempotency on your side. Retries reuse the same id.
X-Zentra-Signature — HMAC-SHA256 of the raw body, hex-encoded, computed with your subscription’s signing secret.

Verifying the signature

Always verify X-Zentra-Signature before processing. Use a constant-time comparison.

// Verify a Zentra outbound webhook in Node.js
const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Retries & idempotency

2xx response → delivery succeeded.
4xx (client error) → no retry; logged for review.
5xx or network error → retried with exponential backoff up to the configured cap.

Treat X-Zentra-Delivery-Id as an idempotency key. Two deliveries with the same id are duplicates from a retry; process the first, ignore the rest.

Inbound webhooks

Inbound webhook endpoints accept POSTs that create or update records inside Zentra. The two paths in production today:

Endpoint	Purpose
`/api/webhooks/inbound-email`	SendGrid Inbound Parse — creates a ticket from a parsed email.
`/api/webhooks/<name>`	Generic inbound endpoint that delivers the payload to a configured workflow as the trigger event.

All inbound webhooks require a shared-secret header (configurable per endpoint).

Example: inbound email

curl -X POST https://your-zentra/api/webhooks/inbound-email \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Webhook-Secret: " \
  --data-urlencode "[email protected]" \
  --data-urlencode "subject=Cannot connect to VPN" \
  --data-urlencode "text=Auth fails repeatedly from the Frankfurt office."

The payload format matches SendGrid’s Inbound Parse. Multipart attachments are supported and stored against the resulting ticket.

Workflows as an integration layer

When you don’t want to write a custom adapter, the workflow engine can act as your integration glue. A workflow can:

Trigger on any record event.
Branch on conditions over the record’s fields.
Call an outbound HTTP URL with a shaped payload.
Wait for a callback (via inbound webhook + correlation id).

This is the path most customers take for first-pass integrations with PagerDuty, GitHub, monitoring tools, and HR systems while native connectors are being built.

Automation — workflows that fire actions externally
Integrations — built-in connectors and the roadmap
Talk to us — about a programmatic access pattern that’s missing