Events, analytics, inventory, and websites

​

Goal

​

Prerequisites

• An existing S2 bucket
• A StackShift API token

​

Workflow

​

Event delivery release status

​

Pull claims and interruption recovery

​

Create a signed HTTPS subscription

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyS2Event(rawBody, headers, secret, now = Date.now()) {
  const timestamp = headers.get('x-stackshift-timestamp') ?? ''
  const signature = headers.get('x-stackshift-signature') ?? ''
  if (!/^\d+$/.test(timestamp) || Math.abs(now / 1000 - Number(timestamp)) > 300) throw new Error('Expired signature')
  if (!/^v1=[a-f0-9]{64}$/.test(signature)) throw new Error('Invalid signature')
  const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest()
  const received = Buffer.from(signature.slice(3), 'hex')
  if (!timingSafeEqual(expected, received)) throw new Error('Invalid signature')
  return JSON.parse(rawBody.toString('utf8'))
}

​

Durable, idempotent consumption

CREATE TABLE s2_event_inbox (
  event_id uuid PRIMARY KEY,
  payload jsonb NOT NULL,
  received_at timestamptz NOT NULL DEFAULT now(),
  processed_at timestamptz
);
-- Bind the verified event.id and JSON body as parameters.
INSERT INTO s2_event_inbox(event_id,payload) VALUES ($1,$2)
ON CONFLICT (event_id) DO NOTHING;

​

Pause, rotate, inspect and replay

• PATCH /event-subscriptions/{subscriptionID} with enabled:false pauses new claims; enabled:true resumes them. Already in-flight requests may finish.
• DELETE /event-subscriptions/{subscriptionID} removes the subscription, pending deliveries and delivery history. The dashboard asks for confirmation and clears the deleted subscription from its recovery view. Objects remain available; already in-flight requests may finish.
• PATCH the same URL with rotate_secret:true returns a replacement secret once. Update the receiver immediately; an in-flight request may still be signed with the old secret. Retain the previous receiver-side secret briefly if accepting those requests is intended.
• GET /event-subscriptions/{subscriptionID}/history returns up to 50 deliveries with attempts, result codes and failures. Pass the returned next_cursor as before for older results.
• Failures retry with exponential backoff, starting at 30 seconds and capped at one hour. The tenth failed attempt exhausts automatic delivery. Network timeouts may mean the receiver already accepted an event; delivery is at least once.
• POST /event-deliveries/{deliveryID}/replay explicitly requeues a delivered or exhausted push delivery on an enabled subscription. Repeated clicks while it is pending do not enqueue duplicates. The stable event ID remains unchanged. Attempt history is retained and a failed replay after exhaustion requires another explicit replay.
• Request bodies are bounded by the stored event payload, responses are retained up to 2 KiB, and each outbound request has a 10-second timeout. Never treat an HTTP response as proof that downstream business processing completed.

​

Managed object events

• Event types are object.created, object.overwritten, and object.deleted.
• Subscriptions can filter by object-key prefix and suffix.
• S2 stores deliveries in a managed queue; clients pull batches and acknowledge each delivery.
• Acknowledgement can mark processing complete or request another attempt after a recoverable failure.
• Pull and acknowledgement operations remain tenant- and bucket-authorized through the StackShift control plane.

​

Analytics and access logs

​

Inventory exports and catalogs

​

Static websites and custom domains

​

Expected result

​

Common failures

​

Related guides