Eventos a tu cola o a tu bucket

Los mismos eventos de los webhooks pueden llegar a tu infraestructura por otras dos vías, sin exponer un endpoint HTTP:

Vía	Para qué	Latencia
Cola SQS o tema SNS	Procesar eventos casi en tiempo real en tu cuenta de AWS	Segundos
Export diario a S3 (NDJSON)	Alimentar analítica o un almacén de datos con el día completo	Una vez al día

Cómo se configuran hoy

Ninguna de las dos tiene aún pantalla propia en el panel: se configuran con la API de administración (/api/services/app/...) usando una sesión de administrador con los permisos indicados. Ver Ámbitos de administración para automatizarlo con una clave.

En los ejemplos, $BASE es la dirección de tu plataforma y $TOKEN el token de tu sesión de administrador.

Cola SQS o tema SNS

Una suscripción de webhook puede tener como destino tu cola SQS o tu tema SNS en vez de una URL HTTPS. El fan-out, los reintentos, el registro de entregas y el reenvío manual son los mismos; solo cambia el último paso.

Necesitas el permiso Suscripciones webhook (Pages.Loyalty.Webhooks) y que el plan incluya webhooks.

Preparar AWS

Crea la cola (o el tema). Se admiten colas y temas .fifo.
Crea una clave de acceso de IAM con permiso solo para sqs:SendMessage sobre esa cola (o sns:Publish sobre ese tema).

IncentIA no usa su propia identidad de AWS como alternativa: las credenciales son obligatorias.

Crear la suscripción

POST /api/services/app/WebhookSubscription/Create:

curl -s -X POST "$BASE/api/services/app/WebhookSubscription/Create" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Eventos a SQS",
    "destinationType": 1,
    "targetUrl": "https://sqs.eu-west-1.amazonaws.com/123456789012/incentia-events",
    "awsAccessKeyId": "AKIA...",
    "awsSecretAccessKey": "...",
    "secret": "secreto-de-firma-opcional",
    "eventTypes": [2, 14, 18]
  }'

Campo	Valor
`destinationType`	`0` = HTTP (por defecto), `1` = SQS (`AwsSqs`), `2` = SNS (`AwsSns`)
`targetUrl`	SQS: URL de la cola, `https://sqs.<región>.amazonaws.com/<cuenta de 12 dígitos>/<cola>`. SNS: ARN del tema, `arn:aws:sns:<región>:<cuenta>:<tema>`
`awsAccessKeyId`, `awsSecretAccessKey`	Obligatorias con SQS o SNS
`secret`	Opcional. Si lo pones, cada mensaje lleva `X-Signature`
`eventTypes`	Lista de tipos de evento (ver Eventos del ciclo de vida)

Solo se admite la partición pública de AWS (aws). La región sale de la propia URL o ARN.
El secreto de AWS se guarda cifrado y no se puede leer después. Al editar, déjalo vacío para conservarlo. Al pasar a HTTP se borran las credenciales.

Qué recibes

Cuerpo: exactamente el mismo JSON que recibiría un webhook HTTP.
Atributos del mensaje: las cabeceras X-Event-Type, X-Timestamp, X-Correlation-Id, X-IncentIA-Idempotency-Key y, con secreto, X-Signature, como atributos de tipo String con el mismo nombre y valor. La firma se calcula igual que en Verificar la firma.
Colas y temas FIFO: MessageGroupId es subscription-<id> y MessageDeduplicationId es la clave de idempotencia, de modo que AWS descarta un reenvío que ya aceptó (ventana de 5 minutos). El orden entre eventos no está garantizado.
Deduplica siempre por X-IncentIA-Idempotency-Key: puede haber entregas repetidas.

Reintentos y fallos

Respuesta de AWS	Tratamiento
Limitación (throttling, HTTP 429)	Se reintenta, como un `429` HTTP
Error `5xx` o sin respuesta	Se reintenta, como un `5xx` HTTP
Cualquier otro error `4xx` (sin permiso, cola o tema inexistente, clave inválida, mensaje demasiado grande)	Fallo definitivo de esa entrega
Destino o credenciales que ya no son válidos	Fallo definitivo

Los fallos cuentan para la desactivación automática de la suscripción, igual que en HTTP (ver Entrega y reintentos). El registro de entregas guarda solo AWS <código> (HTTP <estado>), sin el texto de AWS.

Export diario a S3

Cada día se deja en tu bucket un fichero con todos los eventos del día UTC anterior, sin necesidad de suscripciones. Es una exportación programada de tipo events.

Necesitas el permiso Exportaciones programadas del flujo de eventos (Pages.Exports.Scheduled.Events), además del de exportaciones programadas. Se vuelve a comprobar al usuario que la creó en cada ejecución.

Contenido

NDJSON (UTF-8, una línea JSON por evento, ordenadas):

{"schemaVersion":1,"eventId":"7b1c...","eventType":"ParticipationCreated","event":"participation.created","occurredAt":"2026-11-01T10:15:02Z","recordedAt":"2026-11-01T10:15:02Z","data":{"attemptId":991,"campaignId":17}}

eventId identifica el evento: deduplica por él.
event es el nombre con puntos (participation.created); en los eventos antiguos que no lo tienen, coincide con eventType.
data es el data del webhook sin datos personales: se eliminan nombres, correo, teléfono, dirección, fecha de nacimiento, IP, etc. Quedan los identificadores, códigos e importes como claves de cruce.
Una exportación nunca lleva datos personales y no admite includePii.

Dónde queda

Un fichero por día y de forma idempotente. En tu bucket:

{prefijo}events/dt=AAAA-MM-DD/events_AAAAMMDD.ndjson

Una nueva ejecución del mismo día sobrescribe ese objeto con el mismo contenido (salvo que un borrado por RGPD haya depurado alguna fila entremedias). La partición dt= es compatible con Hive.

Crear la exportación

POST /api/services/app/ScheduledExport/Create:

curl -s -X POST "$BASE/api/services/app/ScheduledExport/Create" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Eventos diarios",
    "exportType": "events",
    "format": "ndjson",
    "cadence": 1,
    "runAtUtcHour": 3,
    "destination": 4,
    "s3": {
      "bucket": "mi-bucket",
      "region": "eu-west-1",
      "prefix": "incentia/",
      "accessKeyId": "AKIA...",
      "secretAccessKey": "..."
    },
    "isActive": true
  }'

Campo	Notas
`exportType`	`events`, con `format` `ndjson` (el único admitido)
`cadence`	`1` = diaria
`runAtUtcHour`	Hora UTC de ejecución, 0-23
`destination`	`4` = bucket propio (`CustomerS3`). También valen `2` (almacenamiento privado de IncentIA con enlace, sin necesidad de bucket) y `3` (SFTP). El enlace por token (`1`) no se admite
`s3.bucket`, `s3.region`	Región obligatoria en AWS
`s3.serviceUrl`, `s3.forcePathStyle`	Para almacenamiento compatible con S3: URL `https://` de su endpoint
`s3.prefix`	Prefijo de claves; vacío = raíz del bucket
`s3.accessKeyId`, `s3.secretAccessKey`	Clave de escritura. El secreto se guarda cifrado y no se devuelve
`campaignId`, `preset`, `columns`	Déjalos vacíos: es un export de toda la cuenta

Da a IncentIA una clave que solo pueda s3:PutObject bajo ese prefijo. Al editar, un secreto vacío o *** conserva el guardado; cambiar el bucket, el endpoint o el id de clave obliga a escribir el secreto de nuevo.

Para ejecutarlo ya, POST /api/services/app/ScheduledExport/RunNow?id=<id>; el historial está en GetHistory.

Límites

El origen son los eventos que la plataforma conserva 14 días por defecto: un día que no se exportó solo se recupera con RunNow al día siguiente, porque siempre se exporta el día anterior.
Un endpoint S3 compatible no puede apuntar a direcciones internas o privadas.
La pantalla Exportaciones programadas (/app/main/loyalty/exports) lista estas exportaciones, pero su selector de destino no ofrece el bucket propio.

Cola SQS o tema SNS​

Preparar AWS​

Crear la suscripción​

Qué recibes​

Reintentos y fallos​

Export diario a S3​

Contenido​

Dónde queda​

Crear la exportación​

Límites​

Relacionado​