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_creditorclient: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
| Failure | Response |
|---|---|
| Signature or timestamp is invalid | Return a permanent client error and do not enqueue or disclose verification details. |
| Duplicate event arrives | Return success after confirming the original durable record; do not repeat side effects. |
| Queue is unavailable | Return a retryable failure such as 503 rather than acknowledging data loss. |
| Endpoint redirects | Fix the configured final HTTPS URL because redirects are permanent delivery failures. |