Skip to content
Guía del Centro de ayuda · API para desarrolladores
5 min de lecturaVerificado 2026-11-16

Webhooks y eventos

Suscríbete a eventos en tiempo real (añadido, eliminado, escaneado, actualizado) y verifica firmas HMAC-SHA256.

En esta guía

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. 1
    Push Webhooks (Push Webhook Dispatcher): Devoluciones de llamada salientes HTTPS POST en 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 = 10 fallos consecutivos, enfriamiento de 30 minutos).
  2. 2
    Pull Webhooks (Webhook Pull API): Una API de consulta de cola sin prefijo (GET /webhook-payload / GET /api/v3/webhook-payload y POST /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-Signature frente a los bytes sin procesar de la solicitud HTTP original utilizando crypto.timingSafeEqual antes 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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
ENTREGA DE WEBHOOKS EN MODO DUAL PUSH Y PULL
ETAPA 01 Bus de eventos de Passinstance
ETAPA 02 Modo 1: Entrega Push Webhook (Push Webhook Dispatcher)
1
Validar URL destino (Webhook URL Validator: bloquear IPs privadas/SSRF)
2
Firmar carga útil (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST al endpoint HTTPS del cliente (User-Agent: Passinstance-Webhook/2.0)
4
Ante 5xx / Timeout (10s defecto): Reintentar hasta 5x con backoff exponencial +-- 5. Tras 10 fallos consecutivos: Abrir disyuntor (enfriamiento de 30 minutos)
ETAPA 03 Modo 2: Cola Pull Webhook (Webhook Pull API)
-- 1. Encolar carga útil del evento en el búfer pull del inquilino -- 2. Cliente tras cortafuegos consulta: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Cliente confirma el cursor procesado: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Endpoints de gestión de suscripciones (Webhooks API)

MétodoEndpointFinalidad
GET/api/v1/webhooksRecupera el resumen de webhooks del espacio de trabajo y las estadísticas de entrega.
GET / POST/api/v1/webhooks/subscriptionsLista o crea suscripciones salientes de webhooks (events, url HTTPS, filtros opcionales).
PATCH/api/v1/webhooks/subscriptions/:idActualiza eventos suscritos, estado activo o URL del endpoint de destino.
DELETE/api/v1/webhooks/subscriptions/:idElimina una suscripción de webhook.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRota el secreto de firma HMAC-SHA256 de una suscripción.
POST/api/v1/webhooks/subscriptions/:id/testEnvía una entrega de prueba diagnóstica y restablece el estado del disyuntor.
GET/api/v1/webhooks/eventsDevuelve metadatos canónicos WebhookEventType y cargas útiles de ejemplo.
GET/api/v1/webhooks/historyInspecciona 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ónicoValores webhook event asignadosCaso de uso principal
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSincronizar passId, externalId y el enlace inteligente con el registro de contacto en CRM.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGReflejar el nivel de fidelización actualizado, externalId o saldo prepago en un ERP externo.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDMarcar un código de cupón como consumido o revocado en la base de datos de tienda online.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADActivar flujo de bono de bienvenida cuando el pase se instala por primera vez.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDRegistrar adopción multidispositivo (por ejemplo, iPhone + Apple Watch emparejado).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDActualizar el estado de desinstalación/baja en el CRM o iniciar secuencia de reactivación.
pass_template_createdTEMPLATE_CREATEDAprovisionar metadatos de campaña correspondientes en sistemas externos.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDRefrescar mapeos de campos de plantilla en caché o ajustes de bundleId.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDRegistrar visitas en tienda, acumulación de fidelización, entrada en geovalla o check-in en BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTRegistrar envíos de notificaciones push en pantalla de bloqueo o hitos de campaña en la cronología del cliente.
message_failedMESSAGE_FAILEDAlertar 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:

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

Verificación de firma 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);
}

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 2xx o tiempos de espera agotados de 10s (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), circuitOpenedAt abre 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)

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 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:

JSON
{
  "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.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.