Pull-Mode Webhooks
Pull-mode is an alternative way to receive webhook events. Instead of Passcreator pushing events to a URL on your server, events are stored for you to retrieve on your own schedule by calling two dedicated endpoints.
Pull-mode is useful when you cannot expose a publicly reachable endpoint, when your server has intermittent connectivity, or when you prefer to process events in batches.
Pull-mode subscriptions are created through the same Subscribe endpoint you already use for push-mode webhooks. Only the delivery mechanism differs — the event types and payload shapes are identical to their push-mode counterparts.
How It Works
- Create a subscription with pullMode: true using the standard subscribe endpoint. No target URL is required.
- As events are triggered in your account, Passcreator stores the payloads for your customer account.
- Your application calls GET /api/v3/webhook-payload periodically to retrieve unacknowledged payloads.
- After processing them, your application calls POST /api/v3/webhook-payload/acknowledge to mark them as handled so they are not returned again.
Retention: Unacknowledged payloads are kept for 30 days. Acknowledged payloads are removed about 24 hours after acknowledgment. If you do not poll at least every 30 days, older events will be permanently deleted.
Payload signing and retry configuration do not apply to pull-mode. Delivery is considered confirmed once you acknowledge a payload.
Subscribe in Pull Mode
Creates a pull-mode webhook subscription. Uses the same endpoint as a regular subscribe request but sets pullMode to true and omits target_url.
Request Body
- Name
event- Type
- string
- (mandatory)
- Description
The event type to subscribe to. See the Webhooks Overview for the full list.
- Name
pullMode- Type
- boolean
- (mandatory)
- Description
Must be set to true to create a pull-mode subscription. When true, target_url is not required and any retryEnabled or signPayload values are ignored.
See Subscribe to Webhooks for the full reference, including how to scope the subscription to a specific template.
Example Request
HTTP header
POST /api/hook/subscribe HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json
Request body
{
"event": "pass_created",
"pullMode": true
}
Success Response (201)
{}
Pull Unacknowledged Payloads
Returns payloads stored for your customer account that have not yet been acknowledged, oldest first.
URL Parameters
This endpoint has no path parameters.
Example URL
Request URL
https://app.passcreator.com/api/v3/webhook-payload
https://app.passcreator.com/api/v3/webhook-payload?webhookId=aa000001-aaaa-aaaa-aaaa-aaaaaaaaaaaa&limit=50
Optional Query Parameters
- Name
webhookId- Type
- string
- (optional)
- Description
Return only payloads that were produced by the webhook subscription with this identifier.
- Name
limit- Type
- integer
- (optional)
- Description
Maximum number of payloads to return in this response. Default is 100, maximum is 500. Values outside this range are clamped.
- Name
since- Type
- string
- (optional)
- Description
ISO 8601 timestamp. Only payloads triggered strictly after this point in time are returned. Useful for resumable polling without acknowledging.
Authorization
- Name
Authorization- Type
- string
- (mandatory)
- Description
HTTP Header containing your API key.
HTTP header
GET /api/v3/webhook-payload HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Returned Values
The response follows the standard V3 response envelope. data is an array of payload objects in chronological order.
- Name
data[].id- Type
- string
- (mandatory)
- Description
Unique identifier of this stored payload. Pass this value as upTo to the acknowledge endpoint.
- Name
data[].webhookId- Type
- string
- (mandatory)
- Description
Identifier of the webhook subscription that produced this payload.
- Name
data[].type- Type
- string
- (mandatory)
- Description
The event type as a string (e.g. pass_created, pushnotification_registered). See Webhooks Overview.
- Name
data[].triggeredOn- Type
- string
- (mandatory)
- Description
UTC timestamp in YYYY-MM-DD HH:MM:SS format indicating when the event occurred.
- Name
data[].payload- Type
- object
- (mandatory)
- Description
The event body. Its structure is identical to the JSON body that would be POSTed to a push-mode target URL for the same event. See Pass Hooks, Pass Template Hooks, Appscan Hooks, and Message Hooks for event-specific fields.
responseMetaData.resultsThisPage reports how many payloads this response contains, and responseMetaData.resultsTotal reports the total number of unacknowledged payloads that match the filters.
Error Responses
- 401 Unauthorized — the Authorization header is missing or the API key is invalid.
- 400 Bad Request with message Invalid since parameter. Expected ISO 8601 format. when the since query parameter cannot be parsed.
Example Response
Success Response (200)
{
"statusCode": 200,
"success": true,
"description": "Webhook payloads retrieved.",
"responseMetaData": {
"resultsTotal": 3,
"resultsThisPage": 1
},
"data": [
{
"id": "bb000001-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
"webhookId": "aa000001-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
"type": "pass_created",
"triggeredOn": "2026-04-21 09:15:30",
"payload": {
"identifier": "12fd53c5-863e-4056-9dbf-2525fa175523",
"passId": "12fd53c5-863e-4056-9dbf-2525fa175523",
"uniqueIdentifier": "122501adfa977d7.55989831",
"createdOn": "2026-04-21 09:15:30",
"passTemplate": "Loyalty Card",
"userProvidedId": "",
"linkToPassPage": "https://app.passcreator.com/passinstance/show?passInstance[__identity]=abc123-456weqf489-46wefa",
"passTemplateGuid": "02fd53c5-863e-4056-9dbf-2525fa171123",
"genericProperties": {
"my-id": "12345678"
}
}
}
]
}
Acknowledge Payloads
Marks payloads as processed so they are no longer returned by the pull endpoint. Acknowledged payloads are removed about 24 hours after acknowledgment.
URL Parameters
This endpoint has no path or query parameters.
Example URL
Request URL
https://app.passcreator.com/api/v3/webhook-payload/acknowledge
Authorization
- Name
Authorization- Type
- string
- (mandatory)
- Description
HTTP Header containing your API key.
Example HTTP Header
HTTP header
POST /api/v3/webhook-payload/acknowledge HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json
Request Body
- Name
upTo- Type
- string
- (mandatory)
- Description
The id of a payload returned by the pull endpoint. Every unacknowledged payload for your account whose triggeredOn is less than or equal to that payload's triggeredOn is marked as acknowledged.
Acknowledgment is idempotent. Sending the same upTo twice is safe — the second call returns "acknowledged": 0 because those payloads are already marked as processed.
Example Request
Request body
{
"upTo": "bb000001-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
}
Returned Values
- Name
data.acknowledged- Type
- integer
- (mandatory)
- Description
The number of payloads that were newly marked as acknowledged by this call.
Error Responses
- 401 Unauthorized — the Authorization header is missing or the API key is invalid.
- 400 Bad Request with message Missing required parameter: upTo (payload ID). when the request body does not contain a string upTo.
Example Response
Success Response (200)
{
"statusCode": 200,
"success": true,
"description": "3 payload(s) acknowledged.",
"data": {
"acknowledged": 3
}
}
Limitations
- No payload signing. Pull-mode payloads are not signed. The public key endpoint is not relevant for pull-mode subscriptions.
- No retry configuration. Retry settings only apply to push-mode deliveries. A pull-mode payload stays available until you acknowledge it or it expires.
- Unsubscribe via API is not supported. The Unsubscribe endpoint identifies subscriptions by target_url, which pull-mode subscriptions do not have. Remove pull-mode subscriptions through the Passcreator web UI.
- Poll regularly. Payloads older than 30 days are deleted even if they have not been acknowledged.