---
title: "VM and pod events"
method: POST
path: "vmEvent"
tags: ["Webhooks"]
---

# VM and pod events

`POST vmEvent` (webhook)

Sent when a VM starts, or a VM or pod stops, is terminated, is interrupted or recovers, to each enabled webhook that lists the event or lists none.
vm.running: a VM reached running from deploying, on its first start, on every later start of a stopped or failed VM and on every restart, a reboot of a running VM included; or a VM or pod recovered from an interruption. A pod's start, first or later, sends none. vm.stopped: a VM or pod was stopped. vm.terminated: a VM or pod was terminated. vm.interrupted: a VM or pod stopped serving through no action of yours, for example because its node went offline. It usually recovers on its own and sends vm.running again; one still interrupted after 7 days, or whose node is removed, is ended instead: a pod as terminated, which sends vm.terminated, and a VM as stopped, which sends no event.
The events cover the VMs and pods your organization lists; the nodes of a managed Kubernetes cluster send none. Delivery is at least once: the same change can occasionally be recorded as a second event, with a new event id and a new delivery id.

## Headers

- `X-OpenRelay-Signature` string, required
- `X-OpenRelay-Event` string, required
- `X-OpenRelay-Delivery` string, uuid, required
- `User-Agent` 'OpenRelay-Webhook/1.0', required
- `X-VectorLay-Signature` string, required
- `X-VectorLay-Event` string, required
- `X-VectorLay-Delivery` string, uuid, required

## Payload

- VmWebhookEvent: The body of a vm.running, vm.stopped, vm.terminated or vm.interrupted delivery. Pods send the same events with the same body.
  - `created_at` string, date-time, required: When the event was recorded, RFC 3339 in UTC to the second.
  - `data` object, required
    - `endpoint` string, required: Its HTTPS endpoint; an empty string when it has none.
    - `status` string, required: Its status when the event was sent: running, stopped, terminated or interrupted, normally the one the event names.
    - `vm_id` string, required: The VM's or pod's id.
  - `id` string, required: The event's id, evt_ followed by a UUID, new each time an event is recorded. A retry of a delivery carries the same id.
  - `type` 'vm.running' | 'vm.stopped' | 'vm.terminated' | 'vm.interrupted', required

## Acknowledgement `2XX`

Delivered. Any 2xx status within 10 seconds counts, and its body is not kept.

## Other responses

- `default`: Any other final status, a connection error, or no answer within 10 seconds fails the attempt, and up to the first 1000 bytes of the response body are kept in the delivery's error message. Redirects are followed, at most 9 (10 requests in all), each hop held to the webhook URL's rules (https, no credentials, no internal address), and the last status counts. A failed delivery is tried at most 3 times: the second attempt about 10 seconds after the first and the third about 60 seconds after the second, each run by a scheduler that checks every 30 seconds, so a retry can come up to 30 seconds later. A retry that comes due while the webhook is disabled or deleted is dropped.

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)