Webhooks
Webhooks allow your server to receive real-time notifications about changes in your Passcreator account.
How Webhooks Work
The idea of webhooks in general is that a server that should be notified about changes (e.g. a pass was created, a user saves a pass on their smartphone) must subscribe for these changes using our subscription endpoint.
The subscribing server or service will provide a unique URL that will be used by our server to push information to the subscribing server. If the subscription is successful, our server will push data to the URL that has been given on subscription.
If the notifications are no longer needed, the subscribing server will call the unsubscribe endpoint to tell us that we should stop pushing information.
A hook can either be tied to a specific template or not, which leaves the decision up to you if you want to receive data for passes of only one template or events of all templates in your account.
The major advantage of this concept is that both servers have less work to do if you compare it to the usual polling mechanism, and the subscribing server is notified about changes in near-realtime.
Passcreator called webhooks REST Hooks in the past. You may find references to REST Hooks in older documentation or APIs.
Signing of Webhook Data
Webhooks contain a signature and a string representation of the data that we have sent. You should use this signature to check the authenticity of the data that you receive.
You can simply check if the signature and the signed string that are both part of the payload we send to you can be verified. To do that, you can receive the public key by calling the endpoint that returns it. One way to verify the signature is to use openssl_verify (with SHA1 as algorithm).
For detailed examples on how to verify signatures, see Verify a Signature.
Available Webhook Events
Passcreator supports the following webhook event types:
Pass Events
| Event Type | Description |
|---|---|
| pass_created | Triggered when a new pass is created |
| pass_updated | Triggered when an existing pass is updated |
| pass_voided | Triggered when a pass is voided (marked as invalid) |
| pushnotification_registered | Triggered when a pass is saved to a device |
| first_pushnotification_registered | Triggered when a pass is saved to any device for the first time |
| pushnotification_unregistered | Triggered when a pass is removed from a device |
See Pass Hooks for detailed information about these events.
Template Events
| Event Type | Description |
|---|---|
| pass_template_created | Triggered when a new template is created |
| pass_template_updated | Triggered when an existing template is updated |
See Pass Template Hooks for detailed information about these events.
App Scan Events
| Event Type | Description |
|---|---|
| app_scan_created | Triggered when a pass is scanned with the companion app |
See Appscan Hooks for detailed information about this event.
Webhook Management Endpoints
To manage your webhook subscriptions, use the following API endpoints:
- Subscribe to Webhooks - Create a new webhook subscription
- Unsubscribe from Webhooks - Remove an existing webhook subscription
- List Active Hooks - View all active webhook subscriptions
- Get Public Key - Retrieve the public key to verify webhook signatures