Skip to content
Avaloi

Webhooks

Send signed HTTP messages to your server when a job finishes, a site or environment changes, a deploy or backup ends, or a domain changes. Manage endpoints and read the delivery log under Company settings.

Parts of this feature are still being built. The Not yet section lists them.

Avaloi can send a signed HTTP POST to your server when something happens in your company, such as a job finishing or a backup completing. Use it to tell your CI that a deploy is done, post to chat, or keep your own records.

Add an endpoint

Owners, admins, and developers can manage webhooks.

  1. Open Company settings, then Webhooks.
  2. Choose Add endpoint.
  3. Enter the Receiver URL: a public https address. Avaloi does not send to private network addresses.
  4. Choose Every event, or Pick events and tick the ones you want.
  5. Choose Create endpoint, then copy the Signing secret. Avaloi shows it once.

Choose Send test event to check your server before real events arrive. The test reaches that endpoint only.

Events sent today

Group Events
Jobs job.succeeded, job.failed, job.cancelled
Environments environment.created, environment.provisioned, environment.deleted
Deploys deployment.succeeded, deployment.failed
Backups backup.completed, backup.failed, backup.restored
Domains and DNS domain.attached, domain.error, domain.removed, domain.primary_changed, dns.zone.active

Every job your company runs sends a job.* event, so you can follow any change, even one without its own event type.

Check the signature

Each message carries an Avaloi-Signature header with a timestamp and an HMAC-SHA256 signature. Join the timestamp, a period, and the raw body, sign that with your secret, and compare. Refuse a timestamp more than five minutes old. Check the signature before you parse the body. The webhook guide has the full format and sample code.

Rotate secret makes a new secret. The old one keeps working for 24 hours, so you can update your server without missing a message.

Retries and the delivery log

Answer with any 2xx status within 5 seconds. If your server fails or times out, Avaloi tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After five deliveries in a row fail every try, Avaloi turns the endpoint off and says why on the page. Choose Turn on when your server is fixed.

Deliveries lists each message with its status, attempts, and last response for 30 days. Choose View to read the request and response, or Redeliver to send it again.

Follow a job without webhooks

Every write that changes a server returns a job. Open GET /v1/jobs/{id}/events for server-sent events, or poll GET /v1/jobs/{id}. Notifications and the activity log record the same changes. See Jobs and progress and Notifications.

API

  • GET /v1/webhooks/events: the event types you can pick
  • GET /v1/webhooks and POST /v1/webhooks
  • PATCH /v1/webhooks/{id} and DELETE /v1/webhooks/{id}
  • POST /v1/webhooks/{id}/rotate-secret and POST /v1/webhooks/{id}/test
  • GET /v1/webhooks/{id}/deliveries, GET /v1/deliveries/{id}, and POST /v1/deliveries/{id}/redeliver

Not yet

The event list in the picker also names events that Avaloi does not send yet: site changes (site.*, environment.updated), domain.active, DNS zone creation and deletion, DNS record changes, plugin updates and vulnerabilities, node status, usage thresholds, and billing and invoice events. You can subscribe to them now; deliveries start when each one is built.

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.