Skip to content
Guia da Central de Ajuda · API de programador
4 min de leituraVerificado 2026-11-16

Webhooks e eventos

Subscreva notificações em tempo real (adicionado, removido, lido, atualizado) e valide assinaturas HMAC-SHA256.

Neste guia

Visão geral

O Passinstance oferece uma arquitetura webhook de modo duplo gerida via /api/v1/webhooks/subscriptions (ou em Definições do Espaço -> Programadores -> Webhooks em /settings/workspace/developer/webhooks) para sincronizar eventos do ciclo de vida Wallet com qualquer infraestrutura:

  1. 1
    Webhooks Push (Push Webhook Dispatcher): Callbacks HTTPS POST em tempo real assinados com segredos HMAC-SHA256 por subscrição (X-Webhook-Signature), protegidos por validação SSRF de destinos, novas tentativas automáticas com recuo exponencial e jitter (DEFAULT_MAX_RETRIES = 5) e um disjuntor (circuit breaker) por endpoint (CIRCUIT_BREAKER_THRESHOLD = 10 falhas consecutivas, arrefecimento de 30 minutos).
  2. 2
    Webhooks Pull (Webhook Pull API): Uma API sem prefixo baseada em consulta de fila (GET /webhook-payload / GET /api/v3/webhook-payload e POST /webhook-payload/acknowledge / POST /api/v3/webhook-payload/acknowledge) concebida para servidores ERP on-premise ou atrás de firewalls sem portas HTTPS públicas expostas.

Importante: Valide sempre o cabeçalho X-Webhook-Signature contra os bytes brutos e não analisados do corpo HTTP utilizando crypto.timingSafeEqual antes de fazer parsing JSON ou executar lógica de negócio. Reserializar um objeto JSON já interpretado altera espaços ou ordem de chaves e invalida o resumo HMAC.

Arquitetura Webhook de Modo Duplo

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ENTREGA WEBHOOK PUSH & PULL EM MODO DUPLO
ETAPA 01 Barramento de Eventos Passinstance
ETAPA 02 Modo 1: Entrega Push Webhook (Push Webhook Dispatcher)
1
Validar URL Destino (Webhook URL Validator: bloqueia IP privado/SSRF)
2
Assinar Payload (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST para Endpoint HTTPS Cliente (User-Agent: Passinstance-Webhook/2.0)
4
Em 5xx / Timeout (10s padrão): Repete até 5x com backoff exponencial e jitter +-- 5. Após 10 falhas seguidas: Dispara Circuit Breaker (pausa de 30 minutos)
ETAPA 03 Modo 2: Fila Pull Webhook (Webhook Pull API)
-- 1. Enfileira payload de evento no buffer pull do inquilino -- 2. Cliente atrás de firewall consulta: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Cliente confirma cursor processado: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Endpoints de Gestão de Subscrições (Webhooks API)

MétodoEndpointFinalidade
GET/api/v1/webhooksObtém o resumo de webhooks do espaço de trabalho e estatísticas de entrega.
GET / POST/api/v1/webhooks/subscriptionsLista ou cria subscrições webhook de saída (events, url HTTPS, filtros opcionais).
PATCH/api/v1/webhooks/subscriptions/:idAtualiza eventos subscritos, estado ativo ou URL de destino.
DELETE/api/v1/webhooks/subscriptions/:idElimina uma subscrição webhook.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRoda o segredo de assinatura HMAC-SHA256 de uma subscrição.
POST/api/v1/webhooks/subscriptions/:id/testEnvia uma entrega de diagnóstico e repõe o estado do circuit breaker.
GET/api/v1/webhooks/eventsDevolve metadados canónicos de WebhookEventType e payloads de exemplo.
GET/api/v1/webhooks/historyInspeciona entregas históricas e registos de tentativas (/api/v1/webhooks/history/:eventHistoryId/attempts).

1. Tipos de Eventos Canónicos e Mapeamento Passinstance database webhook event

WebhookEventRegistry normaliza 31 valores de domínio Passinstance database webhook event internos em 11 strings canónicas WebhookEventType enviadas aos recetores (notações legadas com ponto como pass.created são igualmente mapeadas na criação da subscrição):

WebhookEventType CanónicoValores webhook event MapeadosCaso de Utilização Principal
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSincroniza passId, externalId e ligação inteligente com o registo CRM.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGEspelha escalão atualizado, externalId ou saldo pré-pago num ERP externo.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDAssinala código de vale como usado ou revogado na base de dados de checkout.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADDispara fluxo de bónus de boas-vindas aquando da primeira instalação.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDAcompanha adoção multidispositivo (ex.: iPhone + Apple Watch emparelhado).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDAtualiza estado de desinstalação no CRM ou ativa sequência de recuperação.
pass_template_createdTEMPLATE_CREATEDProvisiona metadados correspondentes da campanha em sistemas externos.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDAtualiza mapeamentos de campos em cache ou definições de bundleId.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDRegista visita em loja, atribuição de pontos, entrada em perímetro GPS ou check-in em BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTRegista entrega de push no ecrã bloqueado ou campanha no histórico do cliente.
message_failedMESSAGE_FAILEDAlerta equipas operacionais ou aciona canal alternativo de SMS/e-mail.

Cabeçalhos HTTP de Push Enviados

Cada pedido POST enviado por Push Webhook Dispatcher inclui:

HTTP
POST /webhooks/passinstance HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
User-Agent: Passinstance-Webhook/2.0
X-Webhook-Event: first_pushnotification_registered
X-Webhook-Id: evt_01hxyz9012ab44c8
X-Webhook-Timestamp: 2026-11-16T10:15:30.000Z
X-Webhook-Signature: sha256=4f8b92c1e0a73d6512f98e4b1c30a9d8721e4f60c3b8a192d4e7f012a3b4c5d6

Verificação de Assinatura HMAC-SHA256 (Node.js / TypeScript)

TYPESCRIPT
import * as crypto from 'crypto';

export function verifyPassinstanceWebhook(
  rawBody: Buffer,
  signatureHeader: string | undefined,
  webhookSecret: string,
): boolean {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
    return false;
  }
  const expectedSignature =
    'sha256=' +
    crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');

  const actualBuffer = Buffer.from(signatureHeader, 'utf8');
  const expectedBuffer = Buffer.from(expectedSignature, 'utf8');

  if (actualBuffer.length !== expectedBuffer.length) {
    return false;
  }
  return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
}

Proteção SSRF, Repetições e Circuit Breaker

  • Validação SSRF de Destino (Webhook URL Validator): Rejeita registos e entregas para loopback (127.0.0.0/8, ::1), redes privadas RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), endereços link-local e IPs de metadados cloud (169.254.169.254).
  • Backoff Exponencial: Respostas não-2xx ou timeouts de 10s (DEFAULT_TIMEOUT_MS) são repetidos até 5 vezes (DEFAULT_MAX_RETRIES) com backoff exponencial e jitter.
  • Disjuntor (Circuit Breaker): Após 10 falhas consecutivas de entrega (CIRCUIT_BREAKER_THRESHOLD), circuitOpenedAt abre o circuito por um período de pausa de 30 minutos (CIRCUIT_BREAKER_COOLDOWN_MS) antes de voltar a sondar.

2. Webhooks Pull (Webhook Pull API)

Quando o servidor funciona atrás de uma firewall corporativa ou NAT sem acesso HTTPS público de entrada, configure um Webhook Pull e consulte eventos em fila via HTTPS de saída em GET /webhook-payload (ou alias GET /api/v3/webhook-payload):

Consultar Payloads em Fila (GET /webhook-payload)

GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Header: x-api-key: pi_live_... (limit predefinido 100, máx. 500)

JSON
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "wpl_01hxyz8801",
        "event": "app_scan_created",
        "createdAt": "2026-11-16T10:18:04.000Z",
        "payload": {
          "scanId": "scan_01hxyz7712ab",
          "passId": "pass_loy_449102",
          "externalId": "crm_cust_44910",
          "decision": "SUCCESS"
        }
      }
    ],
    "nextCursor": "wpl_01hxyz8801"
  },
  "description": "Webhook payloads retrieved successfully",
  "errors": [],
  "statusCode": 200
}

Confirmar Eventos Processados (POST /webhook-payload/acknowledge)

Depois de o seu worker gravar o lote, confirme até ao último ID processado (POST /webhook-payload/acknowledge ou POST /api/v3/webhook-payload/acknowledge) para retirar esses eventos da fila:

JSON
{
  "webhookId": "whk_01hxyz5512",
  "upTo": "wpl_01hxyz8801"
}

Consulte Testes e Depuração e a Referência da API Webhooks para esquemas de payload.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.