API webhooks

Use webhooks when VexylCloud should push events into the rest of your stack automatically.

The practical webhook question is not “do webhooks exist?” It is “what event can we catch, how is it verified, and how do we wire it safely into the tools we already operate?” The current public webhook surface is built around tenant-admin outbound hooks with signed payloads, delivery logging, and workflow-aware event subscriptions.

Tenant-admin webhook management

/api/admin/webhooks supports listing, creating, updating, and deleting tenant webhook configurations with tenant-aware RBAC checks.

Event dispatch and PSA workflows

The platform dispatches outbound workflow events, signs the payload body with HMAC, and records delivery logs so operations teams can troubleshoot what happened.

Best fit

Use webhooks when another system should react to VexylCloud ticket, service, or automation events without polling the API constantly.

Representative configuration shape

{
  "name": "PSA Ticket Updates",
  "url": "https://example.com/hooks/vexylcloud",
  "events": ["ticket.created", "ticket.updated"],
  "is_active": true
}

Outbound delivery shape in the current build

{
  "event": "ticket.updated",
  "timestamp": "2026-03-24T23:11:25.000Z",
  "data": {
    "...": "tenant workflow payload"
  }
}

Headers and verification

Content-Type: application/json
X-Webhook-Event carries the event name
X-Webhook-Signature: sha256=<hmac> signs the request body with the webhook secret
Outbound deliveries use a 10 second timeout and record response status, body, and duration in webhook logs
Stripe billing callbacks verify the incoming stripe-signature before processing invoice or subscription changes

Operational expectations

Tenant-admin webhook routes are permission-checked before configuration changes are accepted.
Secrets are generated and stored for outbound delivery verification.
Receivers should validate X-Webhook-Signature before acting on the body.
Webhook receivers should be idempotent so retries do not duplicate downstream work.
Delivery logs should be reviewed alongside webhook configuration during rollout and incident response.

Typical buyer use cases

Push ticket events elsewhere Send creation, update, or SLA-driven events into another ticketing, orchestration, or notification system.

Trigger internal automations Use VexylCloud webhook events to drive workflow chains in your own tools.

Audit what was sent Review response status, body, and duration in the webhook logging layer when a delivery does not behave as expected.

Use API Examples and Authentication if you want to move from webhook evaluation into the wider external API model.

Webhooks