Skip to main content
TapAce sends an HTTPS POST to your server when something happens to a pass, so you don’t have to poll.

​
Events

​
Add an endpoint

  1. In the dashboard, open Developers → Webhooks. Endpoints are separate for test and live, so pick the right mode first.
  2. Select Add endpoint and enter your URL. It must be a public https:// address.
  3. Choose the events to receive, or All events to also get event types added later.
  4. Copy the endpoint’s signing secret. You’ll use it to verify each request.
Use Send test event on the endpoint’s page to check your server before real events arrive.

​
Payload

Every event has the same shape. It contains no holder details, so fetch the pass by data.pass.id if you need them.
​
string
Unique event ID. A delivery can arrive more than once, so use it to skip duplicates.
​
boolean
true for live passes, false for test passes.
​
string
apple or google.
​
string
exact for Apple, which reports every device. best_effort for Google, which may report late or not at all.
​
string
What triggered the event. For pass.installed: device_registered or google_saved. For pass.removed: device_unregistered, push_token_rejected or google_deleted.
​
string | null
Identifies one Apple device’s copy of the pass and stays the same if it’s re-added. null for Google.
​
object
Where the pass is now. apple.active_devices counts devices that have it. google.observed_state is saved, removed or unknown. apple or google is null when the pass wasn’t issued for that wallet.

​
Keep your records in sync

A webhook reports a change at the moment it happens. To check where a pass is at any time, for example after your server was down, get the pass and read its presence. It holds the same figures as data.presence: Apple’s activeDevices and Google’s observedState. List passes returns presence for every pass on the page.

​
Verify signatures

For Node.js applications, the TapAce SDK verifier accepts both the svix-* and Standard Webhooks webhook-* header names. It requires the original body bytes and the endpoint’s signing secret. The SDK verifies signatures but does not persist or deduplicate events for you. Each request carries svix-id, svix-timestamp and svix-signature headers. Verify them with the endpoint’s signing secret before trusting the payload. The Svix libraries do this for you:
Node.js
verify throws if the signature is wrong or the timestamp is too old. Reply with a 400 in that case.

​
Respond and retry

Verify the signature and durably save or enqueue the event before replying with a 2xx status. Return an error if durable acceptance fails. Run longer business processing in a worker after accepting the event. Any other response counts as a failure, and the delivery is retried automatically with growing delays. Each endpoint’s page in the dashboard lists recent deliveries, and you can resend one from there.