Instant triggers and webhooks

Perkstar’s named Zapier triggers use REST-hook subscriptions. When a Zap with a Perkstar trigger is enabled, Zapier registers its HTTPS callback for that one dotted Perkstar event. Perkstar sends the event as it happens; Zapier does not poll the customer or transaction lists to discover changes.

The official app is available in public Beta. Let it create and manage these subscriptions. Do not also paste a Webhooks by Zapier — Catch Hook URL into Perkstar for the same event unless you intentionally want two independent deliveries.

Subscription lifecycle

The Zap is enabled

Zapier first creates a paused Perkstar webhook for the selected trigger and retains its signing secret. It then explicitly activates the subscription with the unique, unguessable Zapier HTTPS target URL, event, card, and live/test filters. If activation fails, Zapier asks Perkstar to delete the unused endpoint instead of delivering to a Zap whose setup did not finish. The target URL is not exposed as a Zap field.

Perkstar records a matching event

Perkstar durably creates the delivery before scheduling the outbound POST. Events that do not match that named trigger, selected card, or live/test mode are rejected before a delivery row or outbound request is created.

Zapier acknowledges the request

Any 2xx response is success. Zapier then deduplicates and starts the Zap run using the event fields.

The trigger is disabled or removed

When Zapier unsubscribes the trigger, it deletes the app-managed Perkstar endpoint by the ID returned during subscription. Re-enabling the trigger creates a fresh endpoint and signing secret. Historical Zapier tasks remain under Zapier’s retention settings.

One Zapier OAuth connection can own up to 200 Perkstar webhook subscriptions, including a paused row left by an interrupted cleanup or revoked connection. Each enabled instant trigger normally uses one, and a successful Zapier unsubscribe deletes it and releases capacity. If the connection reaches the limit, turn off or remove unused instant triggers and confirm their unsubscribe completed before enabling another one; Perkstar returns 409 webhook_subscription_limit_reached instead of silently replacing an existing subscription. Perkstar derives Zapier’s subscription identity from the connected business and named trigger plus the Zap ID when the runtime supplies it. Zapier marks that field deprecated and optional, so the official integration falls back to the documented REST Hook target URL instead of refusing activation. Perkstar binds the resulting key to the live webhook row rather than a 24-hour response cache. A lost create response, access-token rotation, delayed retry, failed unsubscribe, or reconnect with the same identity can recover the row and secret. When the Zap ID is available, a changed callback URL recovers it too. The activation PATCH applies the current URL, card, and live/test filters. Deleting the row removes the binding immediately, so an off/on cycle cannot be given a deleted subscription ID or a stale cached capacity error.

The first Customer Lifecycle Group Changed or Google Wallet Pass Installed trigger for a business needs one completed warm-up sweep. Perkstar records existing state without replaying the customer base, then tracks changes after that baseline. If the first workflow must catch every new Google install, enable and test the Zap before promoting its install link. Apple installation remains callback-driven.

Event identity

Perkstar sends the official app this common envelope:

{
  "id": "whd_01JEXAMPLE",
  "type": "transaction.created",
  "created": 1785312000,
  "orgId": "org_123",
  "data": {
    "enrollmentId": "enr_123",
    "type": "STAMP",
    "delta": 1,
    "occurredAt": "2026-08-02T10:00:00.000Z"
  }
}

id and X-Perkstar-Delivery-Id identify one logical delivery and remain stable across its automatic retries. created is the source event’s data.occurredAt time expressed as Unix seconds, so it also remains stable. The X-Perkstar-Timestamp signing time and signature are regenerated for each attempt. Zapier uses the stable ID to avoid starting the same logical task twice. The app exposes id, event_type, event_created_at, and organization_id to later Zap steps. It flattens the event-specific data fields onto the same record. event_created_at is the raw created value rendered as ISO 8601; it is not the signing-attempt time. Custom webhook endpoints support manual resend in Perkstar. Zapier-owned subscriptions are app-managed and intentionally hidden from those edit, rotate, delete, test, and resend controls.

Delivery policy

Attempt	Timing
1	Immediately
2	1 minute after the first failure
3	5 minutes after the second failure
4	30 minutes after the third failure

Any HTTP 2xx response succeeds.
A non-2xx, network failure, or response taking longer than ten seconds schedules the next attempt.
An HTTP 410 Gone response is treated as a permanently removed callback: Perkstar exhausts that delivery immediately and pauses the subscription.
After four failed attempts, the delivery is exhausted and retained for support diagnostics.
Delivery is at least once. A receiver and every downstream write must tolerate duplicates.
Different events can arrive out of order. Use data.occurredAt or its equivalent outer created value for business ordering, not the signing timestamp.

Signature handling

Perkstar signs the exact raw body with HMAC-SHA256 and sends X-Perkstar-Signature: t=<unix-seconds>,v1=<hex>. Zapier’s REST Hooks runtime stores Perkstar’s one-time subscription secret and makes it available to the live hook handler. Perkstar returns it only on creation or an authenticated idempotent replay of that same app-owned subscription; normal reads never expose it. The official app verifies the signature over the exact raw bytes with a constant-time comparison and rejects timestamps more than five minutes from receipt. Zapier also gives every active Zap a unique HTTPS target URL; do not disclose or reuse it. Developers building a separate receiver should follow Receive webhooks and apply the same raw-body verification before parsing JSON. Zapier does not support a separate subscription identity-confirmation handshake; callback HMAC verification is performed inside the official app instead.

Testing an instant trigger

Select the named trigger and the intended Perkstar connected account.
If the trigger offers a card filter, choose the explicit active card.
Ask Zapier to test or listen for the trigger.
Perform the corresponding low-risk event in the connected Perkstar business.
Confirm event_type, organization_id, event_created_at, the flattened event-specific fields, and the stable id before mapping later steps.

The test picker requests up to 20 of the most recent matching records from Perkstar’s 90-day recent-event feed. The feed defaults to live events. New Loyalty Transaction and Reward Redeemed also offer Include Test Events; when enabled, both live and test records may be returned. A Card filter, when offered, applies to both recent samples and live delivery. Perkstar applies these filters before sending to Zapier; the app checks them again before starting a Zap run. The diagnostic webhook.test event is for Perkstar’s generic webhook tools and is not exposed as a named Zapier trigger. If no recent match exists, perform the corresponding low-risk event and test again. A sample is not evidence that every optional field will be non-null on a later live event.

Timing and scope of observed triggers

Some triggers are emitted when Perkstar observes a provider or calculated state, rather than directly from a merchant API request:

Wallet Pass Installed fires once when Perkstar first obtains installation evidence for that pass. Apple supplies a device-registration callback. Recently issued Google passes are eligible on the 15-minute projector; older unseen objects use a lower check cadence, and provider responses or projector backlog can extend observation time. Issuing a pass or opening its save link does not fire the trigger.
Card Scanned fires only after a successful online lookup in the Perkstar Scanner. An offline cache-only lookup, dashboard search, or POS customer lookup is outside this trigger’s contract.
Customer Card Expired represents one enrolment reaching one effective expiry instant. If that enrolment is extended and later reaches a different effective expiry, another event can fire. event_created_at reflects the expiry instant, even if projection occurs shortly afterwards.
Customer Lifecycle Group Changed represents movement among Perkstar’s six exclusive lifecycle groups. It does not track saved-segment membership, and an existing customer’s initial baseline classification is intentionally suppressed.
New Customer Referral is created when one loyalty customer refers another customer. It does not report Perkstar merchant, agency, or partner referrals.

Some trigger bodies contain customer or purchaser data. Zap history and every downstream step can retain mapped values. Use only the fields the workflow needs and follow Data and security.

Explore integrations

Zapier

Make

Loyverse POS

Square

Acuity Scheduling

Subscription lifecycle

Event identity

Delivery policy

Signature handling

Testing an instant trigger

Timing and scope of observed triggers

​Subscription lifecycle

​Event identity

​Delivery policy

​Signature handling

​Testing an instant trigger

​Timing and scope of observed triggers

Subscription lifecycle

Event identity

Delivery policy

Signature handling

Testing an instant trigger

Timing and scope of observed triggers