Auth & webhooks
Keep authentication and downstream delivery on the core production contract.
The public integration model uses API keys for authenticated requests and webhooks for downstream delivery, status visibility, and operational sync. This is the default production surface even when higher-level protocol layers exist.
API key auth
Send your key in the X-API-Key header for authenticated production requests.
Webhook lifecycle
Configure destination URL, subscribe to events, send a test delivery, inspect delivery history, and retry failures from the same operational model.
Signature verification
Verify incoming deliveries with X-Pivota-Timestamp and X-Pivota-Signature. The full signing secret is shown only once when rotated.
import crypto from "crypto";
export function verifyPivotaSignature({ rawBody, timestamp, signature, secret }) {
const payload = `${timestamp}.${rawBody}`;
const digest = crypto
.createHmac("sha256", secret)
.update(payload, "utf8")
.digest("hex");
const expected = Buffer.from(`v1=${digest}`);
const received = Buffer.from(signature ?? "");
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}Managed receiver pattern
Managed receivers are configured per account in the developer portal; this receiver contract is not declared in the public OpenAPI. Use one to validate delivery before switching to a merchant or partner endpoint.
Core event catalog
order.created
order.payment_attempted
order.payment_succeeded
order.payment_failed
order.completed
order.refunded
order.cancelled
api.rate_limited
api.request_failed
webhook.test