> ## 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.

# Instant triggers and webhooks

> Understand how Zapier subscribes to Perkstar events, handles retries, deduplicates deliveries, and manages hooks.

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.

<Info>
  The official app is [available in public
  Beta](https://zapier.com/apps/perkstar/integrations). 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.
</Info>

## Subscription lifecycle

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Zapier acknowledges the request">
    Any `2xx` response is success. Zapier then deduplicates and starts the Zap
    run using the event fields.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Warning>
  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.
</Warning>

## Event identity

Perkstar sends the official app this common envelope:

```json theme={null}
{
  "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](/guides/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

1. Select the named trigger and the intended Perkstar connected account.
2. If the trigger offers a card filter, choose the explicit active card.
3. Ask Zapier to test or listen for the trigger.
4. Perform the corresponding low-risk event in the connected Perkstar business.
5. 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.

<Warning>
  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](/integrations/zapier/data-security).
</Warning>


## Related topics

- [Webhooks and instant scenarios](/integrations/make/webhooks.md)
- [Triggers, actions, and searches](/integrations/zapier/triggers-actions.md)
- [Zapier troubleshooting](/integrations/zapier/troubleshooting.md)
- [Connect Perkstar to Make](/integrations/make/setup.md)