Webhooks
Register HTTP endpoints to receive real-time event notifications when things change in your workspace.
Register an endpoint
curl -X POST /api/v1/webhooks \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "...",
"url": "https://hooks.example.com/vmaintain",
"events": ["ticket.created", "monitor.down"]
}'
Payload format
Every delivery is a POST with a JSON body and theX-VMaintain-Signature HMAC header for verification.
{
"id": "evt_01HXK8...",
"event": "ticket.created",
"workspaceId": "...",
"createdAt": "2025-01-15T12:00:00Z",
"data": { ... }
}
Signature verification
Requests are signed with HMAC-SHA256 using the webhook secret returned at creation time. Always verify the signature before processing.
// Node.js / Edge Runtime
import { createHmac } from 'crypto'
function verify(secret, rawBody, signature) {
const expected = createHmac('sha256', secret)
.update(rawBody).digest('hex')
return `sha256=${expected}` === signature
}
Available events
ticket.created
A new ticket was opened in the workspace.
ticket.updated
A ticket field was changed (subject, priority, assignee, etc.).
ticket.status_changed
A ticket moved to a different status.
ticket.resolved
A ticket was marked as resolved.
site.created
A new WordPress site was added.
site.updated
A site record was updated.
monitor.down
A monitor detected the target is unreachable.
monitor.recovered
A previously-down monitor came back up.
task.created
A new task was created.
task.completed
A task was marked complete.
client.created
A new client was added to the workspace.
Retry policy
- Delivery is attempted immediately after the event fires.
- A 2xx response marks the delivery as successful.
- Non-2xx responses trigger up to 5 retries with exponential backoff (1s, 2s, 4s, 8s, 16s).
- Deliveries that fail all retries are marked as
failedand are visible in the webhook dashboard.