Webhooks

Signed events sent to your own URL when something happens in your organisation.

Built, not open to the public yet

This feature is built and has been tested against simulated hosts and a test database. It has not yet been proven on real hardware, and nothing here can be ordered today.

Not there yet

Not yet run against a real receiver outside our test environment.

Setting one up

Under Account, Webhooks, add an endpoint URL and choose the event types you want. The panel shows the signing secret once. Use Send test event to check your receiver. Each endpoint lists its delivery attempts and lets you replay one. Managing endpoints needs the webhooks permission, which owners and admins hold. See also the API reference.

Events

Group	Types
Servers	`server.provisioning`, `server.active`, `server.suspended`, `server.terminating`, `server.terminated`, `server.failed`
Operations and power	`operation.succeeded`, `operation.failed`, `power.started`, `power.stopped`, `power.rebooted`
Backups	`backup.completed`, `backup.failed`, `backup.restored`, `backup.restore_failed`
Billing	`invoice.paid`, `payment.failed`, `payment.refunded`, `payment.refund_failed`
Support	`ticket.replied`, `ticket.closed`
Status incidents	`incident.opened`, `incident.updated`, `incident.resolved` (platform-wide, sent to every organisation that chose them)

Payloads carry ids only: never a secret, name, address or amount. Fetch the object with the API when you need more. Adding a key or an event type is not a breaking change, so ignore keys you do not know. A breaking change ships as a new payload version, and existing endpoints keep the old one.

Delivery

Delivery is at least once. A retry or replay sends the same event with the same id, so remember the ids you handled and skip repeats.
Each request has the headers Vexelia-Signature, Vexelia-Event-Id, Vexelia-Event-Type, Vexelia-Delivery-Id and Vexelia-Delivery-Attempt.
Delivered means any 2xx within 10 seconds. Anything else is retried with a growing delay, from 30 seconds up to every six hours, with a last attempt 24 hours after the event. Redirects are never followed.
If the last attempt fails, the endpoint is switched off and your organisation's owners and admins are emailed. Fix the receiver, switch it on and replay what you missed from the delivery log. Deliveries are kept for 30 days.
The URL must be https on port 443 or 8443. We refuse private, loopback, link-local and other reserved addresses, checked on every attempt after the name is resolved.
Up to 20 endpoints per organisation. Test events and replays are limited to five a minute per endpoint.

Verify the signature

The signature is t=<unix seconds>,v1=<hex>. Two v1 values appear while a secret is being rotated (the old secret keeps signing for an overlap of 24 hours by default).

Parse t and every v1 from the header.
Compute HMAC-SHA256 over t, a dot, then the raw body bytes, keyed with the whole secret including its whsec_ prefix. Compare in constant time.
Reject the request if t is more than five minutes from your clock.
Skip the event if you already handled its id.

Not yet proven

Delivery has been tested against our own test receiver only. Filtering events by resource is not offered.