Integración de webhooks

Los webhooks de SORI API notifican a sus sistemas los eventos importantes que se producen dentro de la plataforma SORI. Al conectar su propio endpoint, puede reaccionar casi en tiempo real a la actividad de las campañas, la autenticación de dispositivos y las actualizaciones administrativas.

Descripción general

SORI API proporciona funciones de webhook para entregar payloads JSON estructurados en cuanto se producen eventos relevantes. Los webhooks se configuran en SORI Console y admiten las siguientes categorías:

Eventos de campaña (`campaign.*`) Se activan cuando sereconoce una campaña en un dispositivo o cuando el usuario abre la URL de acción.
Eventos de autenticación (`authentication`) Se activan cuando undispositivo inicia sesión correctamente mediante el flujo de autenticación de SORI.
Eventos administrativos de materiales (`admin.material.*`) Notificacionesopcionales que se emiten cuando se crean, actualizan o eliminan materiales en la consola.

Las notificaciones casi en tiempo real permiten:

Análisis instantáneos Supervisar y analizar el rendimiento de las campañasen el momento en que se produce la actividad.
Auditoría de autenticación Conciliar los inicios de sesión de dispositivos consus propios registros de sesión.
Detección de fraude Detectar patrones inusuales en cuantoaparecen.
Paneles en tiempo real Proporcionar datos recientes a los paneles.

Configurar webhooks

SORI ofrece dos formas de configurar los endpoints de webhook:

URL de webhook global

Se establece en la sección Configuración.
Se aplica de forma predeterminada a todas las campañas.
Se utiliza como endpoint de reserva cuando una campaña no define uno distinto.

URL de webhook específica de la campaña

Se configura en la Configuración avanzada de cada campaña.
Sustituye la URL de webhook global para esa campaña concreta.
Resulta útil cuando distintas campañas necesitan un tratamiento específico.

Suscripciones a eventos (Configuración → Webhooks)

En Configuración de la cuenta puede elegir las categorías de eventos que recibirá la cuenta:

Eventos de campaña: suscripción a las notificacionescampaign.* (actividad de impresiones y clics).
Eventos de autenticación: suscripción al eventoauthentication que se emite durante el inicio de sesión del dispositivo.
Eventos administrativos: suscripción a las notificacionesadmin.material.* que se envían cuando los usuarios de la consola gestionan materiales.

De forma predeterminada, las cuentas nuevas reciben eventos de campaña y autenticación. Los administradores pueden modificar estas casillas en cualquier momento; los cambios se aplican de inmediato a los futuros envíos de webhooks.

Para configurar webhooks

Prepare un endpoint HTTPS en su servidor para recibir eventos de webhook.
Configure una de las siguientes opciones:
- Una URL de webhook global en Configuración, o
- URL de webhook específicas en la configuración de cada campaña.
Seleccione las categorías de eventos que desea recibir en Configuración → Webhooks.
Asegúrese de que su endpoint acepte solicitudes POST con payloads JSON y responda rápidamente (en un plazo de cinco segundos).

Tipos de eventos

Cada payload de webhook incluye un campo event que contiene el nombre canónico del evento. Para mayor claridad, ramifique las integraciones nuevas en función de event.

Evento de impresión de campaña (`campaign.impression`)

Se envía cuando una campaña se muestra correctamente en el dispositivo de un usuario. Este evento está disponible cuando se habilitan los Eventos de campaña.

Evento de clic en campaña (`campaign.click`)

Se envía cuando un usuario toca una campaña y se le redirige a la URL de acción. Este evento está disponible cuando se habilitan los Eventos de campaña.

Evento de autenticación (`authentication`)

Se envía cuando un dispositivo completa la autenticación con SORI. El payload contiene los parámetros de consulta proporcionados durante la solicitud de autenticación, que pueden utilizarse para correlacionar el inicio de sesión con sus propios identificadores de sesión.

Gestionar eventos de webhook

Cuando su endpoint recibe un evento de webhook, este incluye un payload JSON con los detalles del evento. A continuación se muestran ejemplos de cada tipo de evento. Los campos marcados con null pueden omitirse por completo si no hay ningún valor disponible.

Esquema del payload

Los siguientes campos se entregan con cada webhook de campaña, salvo que se indique lo contrario.

Campo	Tipo	Descripción
`event`	string	Nombre canónico del evento, como `campaign.impression`, `campaign.click` o `authentication`.
`event_type`	string	Duplicado heredado de `event`; se sigue emitiendo para mantener la compatibilidad con versiones anteriores.
`account_id`	string	Identificador de la cuenta de SORI propietaria de la campaña.
`created_at`	ISO 8601 string	Hora del servidor en la que se creó el objeto del evento.
`timestamp`	ISO 8601 string	Marca de tiempo de entrega añadida justo antes del envío; resulta útil para comprobar la idempotencia.
`activity_id`	string	Identificador único de la impresión o el clic concretos (solo para eventos de campaña).
`device_id`	string	Dispositivo o sesión que activó el evento, cuando está disponible.
`platform`	string	Plataforma del cliente indicada por el SDK (`Android`, `iOS`, etc.).
`metadata`	object	Pares clave-valor personalizados reenviados desde el SDK o la solicitud de autenticación.
`geolocation.viewer_country`	string	País obtenido mediante CloudFront GeoIP (devuelve `Unknown` si no se puede determinar).
`geolocation.viewer_region`	string	Región o estado obtenido mediante la consulta GeoIP.
`geolocation.viewer_city`	string	Ciudad obtenida mediante la consulta GeoIP.
`campaign.id`	string	Identificador normalizado de la campaña, que coincide siempre con el ID de la consola.
`campaign.name`	string	Nombre visible de la campaña en el momento del evento.
`campaign.tags`	string[]	Etiquetas asignadas a la campaña (matriz vacía si no tiene ninguna).
`campaign.image`	string (URL)	URL HTTPS de la imagen en miniatura de la campaña, si se ha configurado.
`material.id`	string	Identificador del material reconocido (solo para eventos de campaña).
`material.name`	string	Nombre del material; se omite si no hay ningún material asociado.
`material.tags`	string[]	Etiquetas almacenadas en el registro del material (matriz vacía si no tiene ninguna).
`material.image`	string (URL)	URL de la imagen de vista previa del material, si está disponible.

Campos heredados

event_type, campaign_id, campaign_name, material_id y material_name son duplicados heredados que se conservan únicamente para mantener la compatibilidad con versiones anteriores y se eliminarán en una próxima versión. Actualice su integración para utilizar el campo event y los objetos anidados campaign y material. Para mayor claridad, los payloads de ejemplo que aparecen a continuación omiten estas claves obsoletas.

Para eventos de impresión:

json

{
  "event": "campaign.impression",
  "account_id": "acc_123456",
  "created_at": "2025-10-14T05:25:12.421Z",
  "activity_id": "act_7890",
  "device_id": "device_abc",
  "platform": "Android",
  "metadata": {
    "session": "abcd-1234"
  },
  "geolocation": {
    "viewer_country": "United States",
    "viewer_region": "Michigan",
    "viewer_city": "Ann Arbor"
  },
  "campaign": {
    "id": "cmp_1234",
    "name": "Fall Promotion",
    "tags": [
      "retail",
      "autumn"
    ],
    "image": "https://cdn.soriapi.com/campaigns/cmp_1234.png"
  },
  "material": {
    "id": "mat_5678",
    "name": "Audio Spot 15s",
    "tags": [
      "audio",
      "15s"
    ],
    "image": "https://cdn.soriapi.com/materials/mat_5678.png"
  },
  "timestamp": "2025-10-14T05:25:12.421Z"
}

Para eventos de clic:

json

{
  "event": "campaign.click",
  "account_id": "acc_123456",
  "created_at": "2025-10-14T05:26:03.009Z",
  "activity_id": "act_7890",
  "device_id": "device_abc",
  "platform": "Android",
  "metadata": {
    "session": "abcd-1234",
    "utm_source": "push"
  },
  "geolocation": {
    "viewer_country": "United States",
    "viewer_region": "Michigan",
    "viewer_city": "Ann Arbor"
  },
  "campaign": {
    "id": "cmp_1234",
    "name": "Fall Promotion",
    "tags": [
      "retail",
      "autumn"
    ],
    "image": "https://cdn.soriapi.com/campaigns/cmp_1234.png"
  },
  "material": {
    "id": "mat_5678",
    "name": "Audio Spot 15s",
    "tags": [
      "audio",
      "15s"
    ],
    "image": "https://cdn.soriapi.com/materials/mat_5678.png"
  },
  "timestamp": "2025-10-14T05:26:03.009Z"
}

Para eventos de autenticación:

json

{
  "event": "authentication",
  "account_id": "acc_123456",
  "created_at": "2025-10-14T05:15:44.832Z",
  "device_id": "device_abc",
  "platform": "Android",
  "metadata": {
    "app_version": "1.8.0",
    "session": "abcd-1234"
  },
  "geolocation": {
    "viewer_country": "United States",
    "viewer_region": "Michigan",
    "viewer_city": "Ann Arbor"
  },
  "timestamp": "2025-10-14T05:15:44.832Z"
}

Metadatos personalizados

El campo metadata es un mapa de pares clave-valor que proporciona el SDK (para eventos de campaña) o los parámetros de consulta de la solicitud de autenticación (para eventos de autenticación). Puede utilizarse para identificar al usuario o dispositivo y proporcionar contexto adicional. Este campo es opcional. Consulte la sección Proveedor de metadatos para obtener más información.

Nota sobre la información de ubicación

Los valores de geolocalización se proporcionan dentro del objeto geolocation. Los datos se basan en una estimación de CloudFront GeoIP y es posible que no siempre sean precisos. Si no se dispone de información exacta, se devuelve el valor Unknown.

Requisitos de la respuesta

Su endpoint de webhook debe:

Responder con un código de estado 2xx para confirmar la recepción.
Procesar los eventos de forma asíncrona, si es posible, para evitar bloqueos.
Gestionar los eventos de forma idempotente (mediante la marca de tiempo o el ID de actividad).
Responder en un plazo de 5 segundos para evitar que se agote el tiempo de espera.

Consideraciones de seguridad

Utilice HTTPS para su endpoint de webhook siempre que sea posible a fin de garantizar la privacidad de los datos.
Valide la estructura del payload entrante y compruebe el valor de event.
Mantenga confidencial su URL de webhook.
Cuando se configuren app_id y secret_key, verifique la cabecera X-SORI-Signature con su copia del payload para confirmar su autenticidad.

Gestión de errores

Si su endpoint no puede recibir eventos, el servidor de SORI API:

Reintentará los envíos fallidos hasta 3 veces.
Aplicará una espera exponencial entre los reintentos.
Descartará el evento una vez agotados todos los reintentos.

Ejemplos de implementación

Python (FastAPI)

python

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    payload = await request.json()
    event = payload.get("event")

    if event == "campaign.impression":
        # Handle impression event
        pass
    elif event == "campaign.click":
        # Handle click event
        pass
    elif event == "authentication":
        # Handle authentication event
        pass

    return {"status": "success"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=3000)

Node.js (Express)

typescript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const event = payload.event;

  if (event === "campaign.impression") {
    // Handle impression event
  } else if (event === "campaign.click") {
    // Handle click event
  } else if (event === "authentication") {
    // Handle authentication event
  }

  res.status(200).send({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});

Integración de webhooks ​

Descripción general ​

Configurar webhooks ​

URL de webhook global ​

URL de webhook específica de la campaña ​

Suscripciones a eventos (Configuración → Webhooks) ​

Para configurar webhooks ​

Tipos de eventos ​

Evento de impresión de campaña (campaign.impression) ​

Evento de clic en campaña (campaign.click) ​

Evento de autenticación (authentication) ​

Gestionar eventos de webhook ​

Esquema del payload ​

Metadatos personalizados ​

Requisitos de la respuesta ​

Consideraciones de seguridad ​

Gestión de errores ​

Ejemplos de implementación ​

Python (FastAPI) ​

Node.js (Express) ​

Integración de webhooks

Descripción general

Configurar webhooks

URL de webhook global

URL de webhook específica de la campaña

Suscripciones a eventos (Configuración → Webhooks)

Para configurar webhooks

Tipos de eventos

Evento de impresión de campaña (`campaign.impression`)

Evento de clic en campaña (`campaign.click`)

Evento de autenticación (`authentication`)

Gestionar eventos de webhook

Esquema del payload

Metadatos personalizados

Requisitos de la respuesta

Consideraciones de seguridad

Gestión de errores

Ejemplos de implementación

Python (FastAPI)

Node.js (Express)