> ## Documentation Index > Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # List recent outbound events > Returns one canonical row per source event, newest first. REST-hook integrations use this endpoint to load representative sample data whose keys and types match the live webhook envelope. Live events are returned by default; request `mode=test` or `mode=all` explicitly when validating sandbox activity. Event rows are retained for 90 days and require the dedicated `EVENTS_READ` scope. ## OpenAPI ````yaml /api/openapi.yaml get /events openapi: 3.1.0 info: title: Perkstar Public REST API version: 2026-05-04.oauth description: | Programmatic access to your Perkstar loyalty data. Two authentication modes are supported: - **API key.** Per-org bearer token issued from Settings → API keys (`pk_live_…` / `pk_test_…`). Right choice for direct integrations, single-tenant POS adapters, and back-office sync. - **OAuth 2.0.** Three-legged authorization-code flow with PKCE, for marketplace listings (Square App Marketplace, Shopify App Store, Toast Partner Marketplace, Lightspeed). The merchant installs your app from the partner marketplace, lands on `/oauth/authorize`, approves the requested scopes, and your server exchanges the code at `/api/oauth/token` for a short-lived access token. See the dedicated OAuth section below. Every endpoint is scoped, rate-limited, and idempotent on POST. POS-adapter builders should start with the `/marketplace/*` endpoints — they collapse the typical "find-or-create customer + enrolment + post transaction" flow into a single round-trip with permanent dedupe via `external_transaction_id`. ## Test credentials Test credentials (`pk_test_…` or OAuth applications in TEST mode) can read API data, create isolated test transactions, and simulate wallet pushes. They cannot create, update, or delete live customers, enrolments, or webhook configuration. Test calls to `/marketplace/accrue` only work with an existing customer and enrolment; `/marketplace/enroll` is live-only. This prevents a sandbox integration from changing live customer records. Copy-paste cURL recipes are published at `/api/v1/curl-recipes.md` for teams that want to test the API before wiring the SDK. ## Response headers (universal) Every response, success or error, carries: - **X-Request-Id** — unique per request. Echo this in support tickets; we can find the exact call in the per-key audit log. - **X-API-Version** — date-versioned schema marker (`2026-05-04` as of writing). 12-month deprecation policy. - **X-RateLimit-Limit** — per-minute quota for the credential. - **X-RateLimit-Remaining** — tokens left in the current window. - **X-RateLimit-Reset** — unix-seconds when the window refills. - **Retry-After** — emitted on 429 only; seconds to wait. The reusable error responses below (`Unauthorized`, `Forbidden`, `NotFound`, `RateLimited`, `ValidationError`) declare these as strongly-typed `headers` so codegen against an error path has them. Success responses inline their `"200"` / `"201"` and rely on this convention rather than per-endpoint header declarations. contact: name: Perkstar url: https://perkstar.co.uk servers: - url: https://dashboard.perkstar.co.uk/api/v1 description: Production security: - bearerAuth: [] paths: /events: get: tags: - Webhooks summary: List recent outbound events description: | Returns one canonical row per source event, newest first. REST-hook integrations use this endpoint to load representative sample data whose keys and types match the live webhook envelope. Live events are returned by default; request `mode=test` or `mode=all` explicitly when validating sandbox activity. Event rows are retained for 90 days and require the dedicated `EVENTS_READ` scope. operationId: listWebhookEvents parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' - in: query name: type description: Repeat or comma-separate dotted event names. schema: type: array items: $ref: '#/components/schemas/WebhookEventName' style: form explode: true - in: query name: cardId schema: type: string description: Return only events whose payload contains this card ID. - in: query name: customerId schema: type: string description: Return only events whose payload contains this customer ID. - in: query name: createdAfter schema: type: string format: date-time - in: query name: createdBefore schema: type: string format: date-time - in: query name: mode schema: type: string enum: - live - test - all default: live responses: '200': description: Recent source events content: application/json: schema: $ref: '#/components/schemas/WebhookEventList' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: parameters: Cursor: in: query name: cursor schema: type: string description: Opaque cursor returned in `next_cursor`. Limit: in: query name: limit schema: type: integer default: 50 minimum: 1 maximum: 200 schemas: WebhookEventName: type: string description: Stable dotted wire-format name for an outbound event. enum: - customer.enrolled - customer.unenrolled - customer.anonymized - customer.group_changed - wallet.installed - card.scanned - card.expired - referral.created - transaction.created - coupon.redeemed - reward.redeemed - tier.changed - ticket.purchased - ticket.cancelled - ticket.refunded - gift.purchased - gift.redeemed - multipass.purchased - membership.purchased - membership.renewed - membership.cancelled - feedback.submitted - automation.fired - broadcast.sent - booking.created - booking.confirmed - booking.attended - booking.no_show - booking.cancelled - webhook.test WebhookEventList: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: data: type: array items: $ref: '#/components/schemas/WebhookEventEnvelope' Pagination: type: object required: - data - has_more - next_cursor - limit properties: has_more: type: boolean next_cursor: type: string nullable: true limit: type: integer WebhookEventEnvelope: type: object required: - id - type - created - orgId - data properties: id: type: string description: | Stable identity for this event representation. Live callback automatic retries reuse the same callback delivery ID. type: $ref: '#/components/schemas/WebhookEventName' created: type: integer format: int64 description: | Unix seconds when the source event occurred. For business events, this is `data.occurredAt` expressed as Unix seconds and remains stable across automatic delivery retries. orgId: type: string description: Perkstar organisation that owns the event. data: type: object additionalProperties: true description: | Event-specific camelCase payload. See the public webhook event catalogue for required, optional, and nullable fields for every event type. Business event payloads include `occurredAt`; the targeted `webhook.test` event includes `triggeredAt` instead. example: id: whd_01JEXAMPLE type: transaction.created created: 1785312000 orgId: org_123 data: transactionId: txn_123 enrollmentId: enr_123 cardId: card_123 type: STAMP delta: 1 balanceAfter: 6 occurredAt: '2026-07-30T10:00:00.000Z' Error: type: object properties: error: type: object required: - type - message - code properties: type: type: string enum: - authentication_error - permission_error - rate_limit_error - validation_error - not_found - idempotency_error - server_error message: type: string code: type: string param: type: string responses: ValidationError: description: Validation failed headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-API-Version: $ref: '#/components/headers/XAPIVersion' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing / invalid / expired API key headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-API-Version: $ref: '#/components/headers/XAPIVersion' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: API key is missing the required scope headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-API-Version: $ref: '#/components/headers/XAPIVersion' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Per-key rate limit exceeded headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-API-Version: $ref: '#/components/headers/XAPIVersion' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' headers: XRequestId: description: | Unique id for this request. Echo this in your support tickets and we can trace the exact call in the audit log on the API key detail page. schema: type: string XAPIVersion: description: | Date-versioned schema marker. The current value is `2026-05-04`. Bumps follow the 12-month deprecation policy documented in the in-dashboard docs page. schema: type: string XRateLimitLimit: description: Total requests permitted per minute for this credential. schema: type: integer XRateLimitRemaining: description: Requests left in the current 60s window. schema: type: integer XRateLimitReset: description: Unix-seconds timestamp when the current window refills. schema: type: integer RetryAfter: description: | Seconds to wait before retrying. Only emitted on 429 responses. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_… / pk_test_… or perk_at_… ```` ## Related topics - [List webhooks](/api-reference/webhooks/list-webhooks.md) - [Receive a perkstar outbound event](/api-reference/outbound-webhooks/receive-a-perkstar-outbound-event.md) - [API availability](/support/api-availability.md) - [Authentication and scopes](/fundamentals/authentication.md) - [Instant triggers and webhooks](/integrations/zapier/webhooks.md)