vastai-webhooks-events

Signed Vast.ai Notification Receiver

Overview

Vast.ai notifications are signed, at-least-once deliveries. Verify the exact raw body before JSON parsing, reject stale timestamps, deduplicate by stable event ID, enqueue durably, and return success only after acceptance.

Prerequisites

• Full subscription keys such as client:low_credit or client:outbid
• Public HTTPS endpoint without redirects or private-address resolution
• Webhook secret store, five-minute replay window, durable queue, and event ledger

Instructions

Step 1: Create a bounded subscription

Discover valid notification types and subscribe only the required full client or host keys. Respect the four-webhook-per-user limit and retain context-specific webhooks when short slugs overlap.

Step 2: Store the one-time secret

Capture the signing secret at create or rotate time because list and update responses do not return it. Test retrieval and rotation ownership.

Step 3: Verify raw delivery

Require POST, read exact body bytes, combine integer X-Vast-Timestamp, a period, and raw body, then compare the HMAC-SHA256 against X-Vast-Signature-256 in constant time.

Step 4: Reject replay and duplicates

Reject missing or malformed headers and timestamps older than 300 seconds. Deduplicate retries using X-Vast-Event-Id or payload event_id.

Step 5: Acknowledge after durable enqueue

Persist the verified event and return 2xx quickly. Process side effects asynchronously and idempotently; the delivery timeout is ten seconds.

Step 6: Test and operate failure paths

Use the provider test delivery, verify rotation, and monitor permanent 3xx/most-4xx failures versus retryable 408, 429, 5xx, timeout, or connection errors.

Authentication

Webhook configuration uses the scoped Vast.ai API key; delivery verification uses the distinct webhook secret. Never log either secret or parse/re-serialize JSON before signature verification.

Tool Discipline

Use Read and Grep to inspect manifests, configuration, provider output, and existing tests before proposing a mutation. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not create, update, destroy, or fund Vast.ai resources without explicit operator approval.

Output

• Subscription keys, webhook ID, and secret-rotation ownership
• Signature, replay, deduplication, enqueue, and idempotency tests
• Delivery health and retry/permanent-failure receipt

Return webhook ID, context keys, test event ID, signature/replay/dedupe results, acknowledgment latency, queue record, and rotation date.

Examples

A client:low_credit delivery is verified from raw bytes, rejected if older than five minutes, deduplicated by event ID, enqueued, and acknowledged with 204 before the worker pages the billing owner.

Error Handling

Resources

• First-party source notes
• Notification webhooks
• List notification types
• Rotate webhook secret