Skip to content
Referência da API REST e SDKs

Documentação para Desenvolvedores Passinstance

Crie integrações em grande escala para Apple Wallet (.pkpass) e Google Wallet. Emita, atualize, valide e transmita notificações em tempo real através de APIs REST prontas para produção.

Obter chaves de API
Bancada interativa — os trechos são atualizados enquanto você digita

Visão geral e endpoints

4 endpoints
Webhooks

Visão geral de Webhooks e verificação de assinatura

Verifique X-Webhook-Signature como HMAC-SHA256 do corpo original exato da solicitação com o segredo da assinatura. Compare em tempo constante e processe os eventos de forma idempotente.

Cabeçalho de assinatura
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Cabeçalho de timestamp
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Proteção contra repetições

Verifique se X-Webhook-Id corresponde ao eventId assinado, elimine eventos duplicados e valide o timestamp assinado conforme a sua política contra repetições.

Eventos suportados

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Resposta esperada

Retorne HTTP 200 OK em até 5.000 ms para confirmar o recebimento

Chave pública de verificação

GET /api/v1/webhooks/public-key retorna a chave pública ativa para verificação de assinatura

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChave de API
Visão geral e endpoints

Criar assinatura de webhook

Registre um endpoint HTTPS para receber notificações de eventos em tempo real assinadas por HMAC sobre emissão, atualização, leitura e remoção de passes.

Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório

Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.

Exemplo: pi_live_98a7b6c5d4e3f2a1

Payload da requisição com a URL HTTPS de destino e matriz de itens tipos de eventos webhook.

Corpo da requisição2 obrigatório(s) • 5 opcional(is)
urlstring (HTTPS URL)
Obrigatório

URL do seu servidor (deve começar com https://, máx. 2048 caracteres).

Exemplo: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Obrigatório

Valores tipos de eventos webhook: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Exemplo: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Chave de API
Visão geral e endpoints

Cancelar inscrição de Webhook

Exclua uma inscrição de webhook ativa pelo seu identificador e interrompa o envio de eventos futuros para esse endpoint.

Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório

Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.

Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de caminho1 obrigatório(s)
idstring (UUID)
Obrigatório

UUID da inscrição de webhook a ser removida.

Exemplo: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChave de API
Visão geral e endpoints

Listar assinaturas de webhooks

Recupere todas as assinaturas de webhooks ativas registradas para o seu espaço de cliente.

Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório

Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.

Exemplo: pi_live_98a7b6c5d4e3f2a1

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPúblico
Visão geral e endpoints

Obter chave pública de assinatura Webhook

Obtenha a chave pública PEM ativa do Passinstance para verificar criptograficamente as assinaturas dos webhooks recebidos.

Códigos de status de resposta

Webhooks baseados em Pull

2 endpoints
Webhooks

Como funcionam os Pull Webhooks e suas limitações

Consuma eventos de passes e leituras em tempo real via webhooks Push assinados por HMAC-SHA256 (com backoff exponencial e disjuntores) ou consulta Pull Webhook para ambientes protegidos por firewall, além de fluxos no-code.

Resiliência Push Webhook

5 tentativas com backoff exponencial com jitter; o disjuntor abre após 10 falhas consecutivas

Consulta Pull Webhook

GET /api/v1/webhook-payload e POST /api/v1/webhook-payload/acknowledge para redes privadas

Gatilhos de fluxo

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Ações de fluxo

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadChave de API
Webhooks baseados em Pull

Consultar eventos pull-webhook na fila

Busque payloads de eventos webhook pendentes via HTTPS GET de saída para ambientes restritos por firewall ou redes privadas sem abrir portas de entrada.

Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório

Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.

Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de consulta3 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeChave de API
Webhooks baseados em Pull

Confirmar eventos pull-webhook

Confirme payloads pull-webhook processados até um ID específico para que sejam marcados como entregues e removidos da fila.

Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório

Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.

Exemplo: pi_live_98a7b6c5d4e3f2a1

Payload da requisição especificando o ID limite superior processado (upTo).

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
upTostring (UUID)
Obrigatório

Último ID de payload webhook processado; todos os eventos até este ID são confirmados.

Exemplo: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Códigos de status de resposta

Eventos Webhook

4 guias
Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de modelo (Template Events)

Notificações webhook HTTP POST enviadas quando um modelo de passe é criado, atualizado, publicado ou excluído.

Modelo criado
POST
TEMPLATE_CREATED

Disparado quando um novo modelo de passe é criado

Modelo atualizado
POST
TEMPLATE_UPDATED

Disparado quando campos, layout ou mecânicas do modelo são alterados

Modelo publicado
POST
TEMPLATE_PUBLISHED

Disparado quando um rascunho é publicado para passes ativos

Modelo excluído
POST
TEMPLATE_DELETED

Disparado quando a exclusão do modelo e revogação na carteira são iniciadas

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de passe (Pass Events)

Notificações webhook HTTP POST que acompanham todas as etapas do ciclo de vida do passe, da criação à remoção do dispositivo.

Passe criado
POST
PASS_CREATED

Disparado imediatamente quando um novo passe é emitido via API REST ou PassFlow

Passe atualizado
POST
PASS_UPDATED

Disparado quando atributos, pontos de fidelidade, nível ou saldo do passe mudam

Passe anulado
POST
PASS_VOIDED

Disparado quando um passe é anulado ou desativado no Apple Wallet e Google Wallet

Primeiro download do passe
POST
PASS_FIRST_DOWNLOAD

Disparado na primeira vez que um cliente resgata ou baixa o passe

Passe baixado
POST
PASS_DOWNLOADED

Disparado em cada download subsequente do pacote ou link do Google Wallet

Passe removido do dispositivo
POST
PASS_REMOVED

Disparado quando o cliente remove o passe do Apple Wallet ou Google Wallet

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de leitura (Scan Events)

Notificações webhook HTTP POST emitidas em tempo real sempre que o código de barras ou NFC de um passe é lido e validado.

Leitura de passe criada
POST
APP_SCAN_CREATED

Disparado quando POST /api/v1/scans ou um scanner registra uma leitura

Metadados do resultado

Inclui passId, serialNumber, templateId, configId, decisão de validação e delta de saldo

Garantia de entrega

Entrega HTTPS POST pelo menos uma vez com cabeçalhos X-Webhook-Id e X-Webhook-Signature

Compatibilidade com fila Pull

Também disponível via GET /api/v1/webhook-payload para PDVs atrás de firewall

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de mensagem e referência de status (Message Events)

Notificações webhook HTTP POST e códigos de status de entrega para notificações push, envios de e-mail e SMS.

Mensagem enviada
POST
MESSAGE_SENTNOTIFICATION_SENT

Disparado quando uma mensagem ou push de passe é enviado

Falha na entrega
POST
MESSAGE_FAILED

Disparado quando um e-mail, SMS ou notificação push falha na entrega

Referência de status da mensagem

QUEUED -> SENT -> DELIVERED (ou FAILED / BOUNCED com código de diagnóstico)

Correlação idempotente

Correlacione eventId e passId no consumidor webhook para desduplicar novas tentativas