Concepts
Platform events
Webhook destinations that receive signed events when pods, jobs, models, batches, endpoints and billing change; verification, retries, pausing and secret rotation.
What you receive
A webhook destination is a URL in a project that receives platform events: a pod started or stopped, a fine-tuning job finished, a batch completed, a dedicated endpoint became ready, credit ran low. Each event is one POST with a JSON body:
{
"id": "evt_…",
"object": "event",
"type": "pod.stopped",
"version": "2026-11-01",
"created_at": "2026-11-13T09:30:00.000Z",
"org_id": "org_…",
"project_id": "prj_…",
"data": { "object": "pod", "id": "pod_…", "name": "trainer", "state": "stopped", "reason": "requested" }
}data names the resource (object, id) and carries the fields the event is about, with the same names the API uses. Fetch the resource by its ID when you need all of it. Events never carry secrets. GET /v1/webhooks/event-types lists every type, its product, and the JSON Schema of its data; a destination subscribes to a list of types or to ["*"].
| Event | Scope | When |
|---|---|---|
pod.running | project | The pod’s container is running (after a start, restart or a move to a new host). |
pod.stopped | project | The pod stopped and its compute was released (by request or for host maintenance); its volume is kept. |
pod.billing_stopped | project | The pod was stopped because the organization ran out of credit, reached a spend limit or was suspended. |
pod.terminated | project | The pod was terminated (deleted). It is not billed from now on. |
pod.preempted | project | An interruptible pod was preempted by on-demand work; it waits for capacity and restarts. |
pod.host_lost | project | The host running the pod stopped responding and was declared lost; the pod is kept and billing stops at the last proven second. |
volume.created | project | A volume was created. |
volume.deleted | project | A volume was deleted (its data is erased). |
file.validated | project | An uploaded file passed validation and can be used. |
file.rejected | project | An uploaded file failed validation; its validation report says why. |
serverless_endpoint.created | project | A serverless endpoint was created. |
serverless_endpoint.updated | project | A serverless endpoint’s settings or release changed. |
serverless_endpoint.deleted | project | A serverless endpoint was deleted; its queued jobs were cancelled. |
serverless_release.created | project | A new release of a serverless endpoint was created (a spec change or a rollback). |
fine_tune.succeeded | project | A fine-tuning job finished successfully. |
fine_tune.failed | project | A fine-tuning job failed. |
fine_tune.cancelled | project | A fine-tuning job was cancelled. |
fine_tune.stopped | project | A fine-tuning job was stopped by the platform (not enough credit for its plan, or billing enforcement). |
fine_tuned_model.available | project | A fine-tuned model is available (its job succeeded and its artefacts are stored). |
batch.in_progress | project | A batch passed validation and its requests started to run (request_counts.failed holds the invalid lines). |
batch.completed | project | A batch finished; its output file is ready. |
batch.failed | project | A batch failed (validation, or it stopped for a reason such as credit). |
batch.expired | project | A batch reached its completion window before every request ran. |
batch.cancelled | project | A batch was cancelled. |
sandbox.ready | project | A sandbox is running on its host and ready to run code. |
sandbox.ended | project | A sandbox ended (on request, at its deadline, when idle, or because of billing, a failure or its host); its files are gone. |
cluster.created | project | A cluster was created: every member was placed on a host and is starting. |
cluster.running | project | Every member of a cluster is running. |
cluster.degraded | project | A member of a cluster failed or lost its host. Nothing is restarted; the other members keep running and billing. |
cluster.stopped | project | A cluster’s members were stopped (out of credit, suspension or host maintenance); its shared volume is kept until it is deleted. |
cluster.deleted | project | A cluster was deleted; its members, network and shared volume are gone. |
evaluation.completed | project | An evaluation finished; its results file is ready. |
evaluation.stopped | project | An evaluation was stopped before every row ran (credit, spend limit or another stop reason); the results of the rows that ran are kept. |
evaluation.failed | project | An evaluation failed (its dataset was invalid, or too many rows errored). |
evaluation.cancelled | project | An evaluation was cancelled. |
dedicated_endpoint.ready | project | A dedicated endpoint has its first healthy replica and serves requests. |
dedicated_endpoint.inactivity_stopped | project | A dedicated endpoint was stopped after its inactivity timeout. |
dedicated_endpoint.failed | project | A dedicated endpoint’s replicas failed to start repeatedly; it has stopped trying until it is changed or restarted. |
billing.balance_low | org | Available credit fell below the low-balance threshold. |
billing.credit_exhausted | org | Available credit reached zero; new compute cannot launch. |
billing.compute_stopped | org | Running compute was stopped by billing enforcement. |
billing.payment_succeeded | org | A payment succeeded and its credit was added (a top-up or an auto-recharge). |
billing.payment_failed | org | A payment failed or was cancelled. |
billing.auto_recharge_failed | org | An automatic recharge failed and auto-recharge was turned off. |
api_key.created | project | An API key was created in the project (its secret is never included). |
api_key.revoked | project | An API key was revoked. |
webhook.test | project | A test event, sent on request to one destination only. |
Organization events (billing.*: low balance, out of credit, compute stopped, payments, auto-recharge) concern the whole organization. A destination receives them only with org_events: true, which whoever sets it needs billing:read for (every member role has it; an API key needs the scope).
Add a destination
The response holds the signing secret (whs_…). It is shown only then (and when you rotate it), so store it with your receiver.
CREATED=$(curl -sS --fail-with-body "$API_BASE_URL/webhooks" \
-H "$AUTH" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
-d '{"url": "https://hooks.example.com/platform", "description": "Ops alerts",
"event_types": ["pod.stopped", "pod.host_lost", "fine_tune.succeeded"]}')
WEBHOOK_ID=$(echo "$CREATED" | jq -r .id)
SIGNING_SECRET=$(echo "$CREATED" | jq -r .secret) # shown only now: store it
echo "created $WEBHOOK_ID ${SIGNING_SECRET:0:4}"Send a test event (webhook.test) to check your receiver, and read the delivery log with each attempt's status code, timing and the start of your response:
curl -sS --fail-with-body -X POST "$API_BASE_URL/webhooks/$WEBHOOK_ID/test" -H "$AUTH" |
jq -r '"test delivery: \(.id) \(.status)"'
curl -sS --fail-with-body "$API_BASE_URL/webhooks/$WEBHOOK_ID/deliveries?limit=20" -H "$AUTH" |
jq -r '.data[] | "\(.event_type) \(.status) \(.attempts)"'Verify every delivery
| Header | Value |
|---|---|
Webhook-Id | The event ID (evt_…): the same on every retry and redelivery |
Webhook-Timestamp | When this attempt was signed, in Unix seconds |
Webhook-Signature | v1= and the hex HMAC-SHA256 of <timestamp>.<raw body> with the secret; during a rotation, two such values separated by a space |
Webhook-Event | The event type |
Webhook-Delivery | The delivery (whd_…); a redelivery has a new one |
A delivery is genuine when any v1 value matches and the timestamp is within five minutes of your clock. Both SDKs do this for you on the raw body:
import { constructWebhookEvent, WebhookVerificationError } from 'hayonix';
/** Your HTTP handler: `rawBody` is the request body exactly as received, before any parsing. */
async function handle(
rawBody: string,
headers: Record<string, string>,
secret: string,
): Promise<number> {
try {
const event = await constructWebhookEvent({ secret, body: rawBody, headers });
// Deliveries can arrive more than once and in any order: dedupe on event.id (also the
// Webhook-Id header), answer 2xx quickly, and do slow work afterwards.
console.log('type:', event.type, 'id:', event.id);
return 204;
} catch (err) {
if (err instanceof WebhookVerificationError) return 400;
throw err;
}
}Delivery, retries and pausing
- Answer
2xxwithin 10 seconds. Redirects are never followed (a3xxis a failure), and only the first kilobyte of your response is kept. - A failed attempt is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h and 8 h (a little jitter added): ten attempts over about 24 hours. Then the delivery is marked failed.
- Delivery is at least once, and the order of events is not guaranteed: deduplicate on
Webhook-Id, and compare the resource's current state when order matters. - A destination that has failed 20 attempts in a row and has not succeeded for 24 hours is paused: its waiting deliveries are given up, the organization's owners and admins get an email, and the audit log records it. Fix the receiver, send a test event, then resume it (
PATCH /v1/webhooks/{webhook_id}with"status": "active") and redeliver what you missed. - Redelivering (
POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver) sends the same event, with the sameWebhook-Id, as a new delivery. - Deliveries and their payloads are kept for 30 days.
- URLs that resolve to loopback, private, link-local or cloud-metadata addresses are refused when delivering, on the address actually connected to.
Rotate the secret
Rotating returns a new secret; the previous one keeps signing next to it for the overlap you choose (default 24 hours, up to a week; 0 revokes it at once). Deploy the new secret to your receiver within the overlap and no delivery fails verification.
curl -sS --fail-with-body -X POST "$API_BASE_URL/webhooks/$WEBHOOK_ID/rotate-secret" \
-H "$AUTH" -H "Content-Type: application/json" -d '{"overlap_seconds": 3600}' |
jq -r '"new secret until the overlap ends: \(.previous_secret_expires_at)"'