Wivly Infrastructure API

Authentication

Every request carries an API key as a bearer token. Create keys from Settings → Developers in your dashboard; the full key is shown once, on creation, and stored only as a hash.

curl https://wivly.me/api/v1/passes \
  -H "Authorization: Bearer wivly_..." \
  -H "Content-Type: application/json" \
  -d '{"templateId":"tpl_123","customer":{"name":"Marco"}}'

Keys can be scoped to specific venues. A venue-scoped key can only act on passes belonging to those venues, which makes it safe to hand to a single location.

Key scopes

Every key carries exactly one scope. Pick the narrowest that does the job.

Rate limits

60 requests per minute per key. Over that, the API returns 429 and the request is not processed — retry after the next minute boundary rather than immediately.

Endpoints

All paths are relative to https://wivly.me/api/v1 and return JSON.

Webhooks

Register an endpoint and Wivly posts to it when something happens. Deliveries are retried on failure.

Events

Verifying a delivery

Every request carries an x-wivly-signature header: HMAC-SHA256 of the raw request body, keyed with your webhook secret. Compare it against the raw bytes before parsing, and use a constant-time comparison.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const received = req.headers["x-wivly-signature"];
const ok =
  received.length === expected.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Idempotency

Each delivery has a stable id in the body, alongside apiVersion "2026-01-01". A retry reuses the id, so store it and ignore ids you have already handled.

Errors

Errors return a JSON body with an error message, and a code where one is useful.

OpenAPI

The machine-readable spec, for Postman, Swagger, Stoplight or code generation. Public and unauthenticated: it describes the surface, not any data.