Descripción general
Passinstance ofrece una arquitectura de webhooks de modo dual gestionada desde /api/v1/webhooks/subscriptions (o en Ajustes del espacio de trabajo -> Desarrollador -> Webhooks en /settings/workspace/developer/webhooks) para sincronizar eventos del ciclo de vida de Wallet con cualquier infraestructura:
-
1
Push Webhooks (
Push Webhook Dispatcher): Devoluciones de llamada salientes HTTPSPOSTen tiempo real firmadas con secretos HMAC-SHA256 por suscripción (X-Webhook-Signature), protegidas por validación de destinos contra SSRF, reintentos automáticos con retroceso exponencial y fluctuación (DEFAULT_MAX_RETRIES = 5), y un disyuntor por endpoint (CIRCUIT_BREAKER_THRESHOLD = 10fallos consecutivos, enfriamiento de30minutos). -
2
Pull Webhooks (
Webhook Pull API): Una API de consulta de cola sin prefijo (GET /webhook-payload/GET /api/v3/webhook-payloadyPOST /webhook-payload/acknowledge/POST /api/v3/webhook-payload/acknowledge) diseñada para servidores ERP locales, tras cortafuegos o sin exposición pública de puertos HTTPS entrantes.
Importante: Verifique siempre el encabezado
X-Webhook-Signaturefrente a los bytes sin procesar de la solicitud HTTP original utilizandocrypto.timingSafeEqualantes de analizar JSON o ejecutar lógica de negocio. Volver a serializar un objeto JSON ya analizado modifica espacios en blanco o el orden de claves e invalida el resumen HMAC.
Arquitectura de webhooks de modo dual
Endpoints de gestión de suscripciones (Webhooks API)
| Método | Endpoint | Finalidad |
|---|---|---|
| GET | /api/v1/webhooks | Recupera el resumen de webhooks del espacio de trabajo y las estadísticas de entrega. |
GET / POST | /api/v1/webhooks/subscriptions | Lista o crea suscripciones salientes de webhooks (events, url HTTPS, filtros opcionales). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Actualiza eventos suscritos, estado activo o URL del endpoint de destino. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Elimina una suscripción de webhook. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Rota el secreto de firma HMAC-SHA256 de una suscripción. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Envía una entrega de prueba diagnóstica y restablece el estado del disyuntor. |
| GET | /api/v1/webhooks/events | Devuelve metadatos canónicos WebhookEventType y cargas útiles de ejemplo. |
| GET | /api/v1/webhooks/history | Inspecciona entregas históricas y registros de intentos (/api/v1/webhooks/history/:eventHistoryId/attempts). |
1. Tipos de eventos canónicos y asignación de webhook event de Passinstance database
WebhookEventRegistry normaliza 31 valores de dominio internos de webhook event en Passinstance database en 11 cadenas canónicas WebhookEventType emitidas a los receptores de webhooks (los alias heredados con punto como pass.created también se asignan limpiamente al crear la suscripción):
WebhookEventType canónico | Valores webhook event asignados | Caso de uso principal |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Sincronizar passId, externalId y el enlace inteligente con el registro de contacto en CRM. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Reflejar el nivel de fidelización actualizado, externalId o saldo prepago en un ERP externo. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Marcar un código de cupón como consumido o revocado en la base de datos de tienda online. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Activar flujo de bono de bienvenida cuando el pase se instala por primera vez. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Registrar adopción multidispositivo (por ejemplo, iPhone + Apple Watch emparejado). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Actualizar el estado de desinstalación/baja en el CRM o iniciar secuencia de reactivación. |
pass_template_created | TEMPLATE_CREATED | Aprovisionar metadatos de campaña correspondientes en sistemas externos. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Refrescar mapeos de campos de plantilla en caché o ajustes de bundleId. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Registrar visitas en tienda, acumulación de fidelización, entrada en geovalla o check-in en BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Registrar envíos de notificaciones push en pantalla de bloqueo o hitos de campaña en la cronología del cliente. |
message_failed | MESSAGE_FAILED | Alertar al equipo de operaciones o activar un canal alternativo de SMS o correo electrónico. |
Encabezados HTTP salientes en modo Push
Cada solicitud POST saliente enviada por Push Webhook Dispatcher incluye:
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
Verificación de firma 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);
}
Protección SSRF, reintentos y disyuntor (Circuit Breaker)
-
Validación de destinos SSRF (
Webhook URL Validator): Rechaza el registro y la entrega hacia direcciones 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), enlaces locales e IP de metadatos cloud (169.254.169.254). -
Retroceso exponencial: Las respuestas distintas de
2xxo tiempos de espera agotados de10s(DEFAULT_TIMEOUT_MS) se reintentan hasta 5 veces (DEFAULT_MAX_RETRIES) con retroceso exponencial y fluctuación aleatoria. -
Disyuntor (Circuit Breaker): Tras 10 fallos consecutivos de entrega (
CIRCUIT_BREAKER_THRESHOLD),circuitOpenedAtabre el disyuntor durante un período de enfriamiento de 30 minutos (CIRCUIT_BREAKER_COOLDOWN_MS) antes de volver a sondear.
2. Pull Webhooks (Webhook Pull API)
Cuando su servidor se ejecuta tras un cortafuegos corporativo o NAT sin acceso HTTPS público entrante, configure un Pull Webhook y consulte los eventos encolados mediante HTTPS saliente con GET /webhook-payload (o el alias GET /api/v3/webhook-payload):
Consultar cargas útiles encoladas (GET /webhook-payload)
GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Encabezado: x-api-key: pi_live_... (valor por defecto de limit: 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 procesados (POST /webhook-payload/acknowledge)
Una vez que su worker haya persistido el lote, confirme hasta el último ID de carga útil procesado (POST /webhook-payload/acknowledge o POST /api/v3/webhook-payload/acknowledge) para desencolar esos eventos:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
Consulte Pruebas y depuración y la Referencia de la API de Webhooks para ver los esquemas de carga útil.
