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
Webhooks Push (
Push Webhook Dispatcher): Callbacks HTTPSPOSTem 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 = 10falhas consecutivas, arrefecimento de30minutos). -
2
Webhooks Pull (
Webhook Pull API): Uma API sem prefixo baseada em consulta de fila (GET /webhook-payload/GET /api/v3/webhook-payloadePOST /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-Signaturecontra os bytes brutos e não analisados do corpo HTTP utilizandocrypto.timingSafeEqualantes 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
Endpoints de Gestão de Subscrições (Webhooks API)
| Método | Endpoint | Finalidade |
|---|---|---|
| GET | /api/v1/webhooks | Obtém o resumo de webhooks do espaço de trabalho e estatísticas de entrega. |
GET / POST | /api/v1/webhooks/subscriptions | Lista ou cria subscrições webhook de saída (events, url HTTPS, filtros opcionais). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Atualiza eventos subscritos, estado ativo ou URL de destino. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Elimina uma subscrição webhook. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Roda o segredo de assinatura HMAC-SHA256 de uma subscrição. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Envia uma entrega de diagnóstico e repõe o estado do circuit breaker. |
| GET | /api/v1/webhooks/events | Devolve metadados canónicos de WebhookEventType e payloads de exemplo. |
| GET | /api/v1/webhooks/history | Inspeciona 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ónico | Valores webhook event Mapeados | Caso de Utilização Principal |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Sincroniza passId, externalId e ligação inteligente com o registo CRM. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Espelha escalão atualizado, externalId ou saldo pré-pago num ERP externo. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Assinala código de vale como usado ou revogado na base de dados de checkout. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Dispara fluxo de bónus de boas-vindas aquando da primeira instalação. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Acompanha adoção multidispositivo (ex.: iPhone + Apple Watch emparelhado). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Atualiza estado de desinstalação no CRM ou ativa sequência de recuperação. |
pass_template_created | TEMPLATE_CREATED | Provisiona metadados correspondentes da campanha em sistemas externos. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Atualiza mapeamentos de campos em cache ou definições de bundleId. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Regista visita em loja, atribuição de pontos, entrada em perímetro GPS ou check-in em BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Regista entrega de push no ecrã bloqueado ou campanha no histórico do cliente. |
message_failed | MESSAGE_FAILED | Alerta 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:
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)
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-
2xxou timeouts de10s(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),circuitOpenedAtabre 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)
{
"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:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
Consulte Testes e Depuração e a Referência da API Webhooks para esquemas de payload.
