PIING
Reading Developers (API and webhooks)Webhooks
Developers (API and webhooks)
- Developer overview
- Webhooks
- Receiving events
- API access
In this guide
- The envelope
- The check-in event
- Other events you can enable
- A worked example
- Next
Search or browse documentation
Developers (API and webhooks) 2 / 4
Webhooks
The events Piing emits and the JSON payload shape they arrive in, including the check-in event and the generic webhook envelope.
Piing emits typed events when activity happens. If you connect a webhook destination, Piing posts a JSON envelope to your URL for each event you have enabled. This article describes the events and the payload they arrive in.
The envelope
A webhook destination receives every event in the same envelope:
event_type is the event identifier, such as piing.checkin.created.event_id is stable across automatic retries and can be used for idempotency.properties holds the event specific fields, described per event below.customer_id is the customer reference, or null for events that are not tied to a customer.timestamp is when the delivery was created.shop is your store domain.
The event specific detail lives in properties. The samples below show the properties for each event.
The check-in event
piing.checkin.created is the central accepted-visit event. It can follow a linked physical-card tap, an approved Apple Wallet VAS tap, a Wallet QR scan at the kiosk or till, a printed scan-in point, Shopify POS, an API route or a controlled manual check-in. The event records the source, so downstream tools can distinguish the journey.
The required fields are checkinId, storeCode and occurredAt. Depending on the destination and what is known about the customer, the event may be enriched with customer detail before it is sent on, but the check-in itself is identified by checkinId.
Other events you can enable
The event catalogue groups events by area. The most useful for a custom integration are:
piing.checkin.created: a customer tapped in.piing.checkin.voided: a staff member voided a check-in. Use it to suppress any follow up that the original check-in triggered.piing.customer.created: a customer was seen for the first time, by tap or by account creation. The source field tells you which.piing.purchase.attributed: a customer placed an order within the attribution window after a check-in. The payload links orderId to checkinId and includes the order total and the hours after the check-in.piing.checkin.no_purchase: the attribution window closed with no purchase after a check-in. Useful for win back.piing.wallet.installed: a customer added a wallet pass. The platform field is apple or google.
There are further events for loyalty point and reward activity, raw tap detection, and selected Shopify order events. Each event in the catalogue carries its own sample payload and a note on when to use it.
Note
Some events are on by default and some are off. Enable only the events your integration needs, so your endpoint is not called for activity you do not use.
A worked example
A piing.purchase.attributed delivery looks like this, with the envelope around it:
Webhook destinations also receive X-Piing-Signature and X-Piing-Timestamp headers. See Webhooks and custom integrations for the exact signing and retry contract.
Next
For how delivery works, how retries are scheduled, and how to verify and de-duplicate events, see Receiving events.
If you need an event that is not in the catalogue, contact us and describe the use case.
Related guides
Was this guide helpful?
Next guide in Developers (API and webhooks)
Receiving events
How to consume Piing webhooks, including verifying the request, handling retries with backoff, and making your handler safe to call more than once.
Still need a hand? Contact us