Webhooks

Con los webhooks, tu aplicación se entera en el momento en que algo ocurre en Edugoverna — se registra una decisión de consentimiento, entra una solicitud ARCO por el portal, falla el envío de un mensaje — sin necesidad de consultar la API en un ciclo de polling. En esta guía verás cómo se firman las entregas, qué forma tiene el sobre de cada evento y el catálogo completo de eventos disponibles.

Registrar un endpoint

Los endpoints de webhook se administran desde la Consola (Integraciones → Webhooks) o mediante la API de gestión de webhooks. Al crear un endpoint eliges un nombre, la URL de destino (solo https://), los eventos a los que te suscribes y, opcionalmente, un secreto propio. Si omites el secreto, el servidor genera uno con prefijo whsec_ y lo devuelve una única vez en la respuesta de creación.

Los webhooks requieren que la organización tenga habilitado el módulo integrations en su licencia. Sin ese módulo, crear un endpoint o activarlo responde 409 INTEGRATIONS_MODULE_REQUIRED, y la Consola lo avisa en Integraciones → Webhooks. Si el módulo se retira después de registrar endpoints, los eventos no se entregan y cada omisión queda en la auditoría de la organización (outbound_webhook_event · skipped_module_disabled). Un partner puede comprobar de antemano si los webhooks salen de una organización con webhooks.available en la conexión.

Cabeceras de cada entrega

Cada entrega es un POST con content-type: application/json a la URL del endpoint, acompañado de tres cabeceras:

Verificación de la firma

Para comprobar que una entrega proviene efectivamente de Edugoverna:

1. Lee la cabecera x-edugoverna-timestamp y el cuerpo crudo de la solicitud (los bytes exactos recibidos — no re-serialices el JSON ya parseado).
2. Construye la cadena firmada como ${timestamp}.${rawBody}, con un punto literal entre el timestamp y el cuerpo.
3. Calcula HMAC-SHA-256(secret, cadenaFirmada) en hexadecimal y compáralo con la cabecera de firma usando una comparación de tiempo constante.
4. Rechaza la entrega si |ahoraEnSegundos - timestamp| > 300 (5 minutos), para protegerte de la repetición de una solicitud capturada.

import crypto from "node:crypto"

const TOLERANCE_SECONDS = 300 // 5 minutos

function verifyWebhook({ rawBody, headers, secret }) {
  const timestamp = headers["x-edugoverna-timestamp"]
  const signature = headers["x-edugoverna-signature"]

  if (!timestamp || !signature) {
    return false
  }

  // Rechaza entregas demasiado antiguas (protección anti-replay).
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp))
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) {
    return false
  }

  // Recalcula la firma sobre `${timestamp}.${rawBody}`.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")

  // Comparación de tiempo constante.
  const a = Buffer.from(expected, "hex")
  const b = Buffer.from(signature, "hex")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

El mismo esquema para los conectores ARCO

Si además recibes acciones de derechos como conector externo (external_post, configurado por el colegio en su portal ARCO), la firma es idéntica: cada despacho llega con x-edugoverna-timestamp y la cabecera de firma que el colegio configuró para el conector, calculada como HMAC(secret, "{timestamp}.{rawBody}") con el secreto del conector. El cuerpo trae en callback la URL a la que respondes y el esquema (signatureScheme, timestampHeader, toleranceSeconds). Tu callback se firma igual, en sentido inverso: envía x-edugoverna-timestamp y x-edugoverna-signature sobre "{timestamp}.{rawBody}"; sin timestamp responde 401 ARCO_ACTION_CALLBACK_TIMESTAMP_REQUIRED, fuera de la ventana de 300 s 401 ARCO_ACTION_CALLBACK_STALE, y con firma incorrecta 401 ARCO_ACTION_CALLBACK_INVALID_SIGNATURE. Un solo verificador sirve para ambos.

Guarda el secreto del webhook con el mismo cuidado que una credencial de API: quien lo conozca puede fabricar entregas válidas. Si sospechas que se filtró, rota el secreto — la rotación genera uno nuevo y lo devuelve una sola vez.

El sobre del evento

Toda entrega comparte el mismo sobre. Los campos específicos del evento viajan dentro de data.

{
  "event": "consent.decision.recorded",
  "sourceType": "consent_request",
  "sourceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "occurredAt": "2026-08-25T14:03:22.511Z",
  "data": {
    "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "status": "granted"
    // ... proyección completa según sourceType
  }
}

Catálogo de eventos

Estos son los 29 tipos de evento del catálogo, agrupados igual que en el selector de la Consola. La suscripción es por lista explícita o mediante el comodín ["*"].

Consentimiento

Eventos sobre el ciclo de vida de una solicitud de consentimiento. sourceType es consent_request. Ver Consentimientos.

{
  "event": "consent.decision.recorded",
  "sourceType": "consent_request",
  "sourceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "occurredAt": "2026-08-25T14:03:22.511Z",
  "data": {
    "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "status": "granted",
    "decisionActorType": "guardian",
    "requestedAt": "2026-08-20T12:00:00.000Z",
    "expiresAt": "2026-09-20T12:00:00.000Z",
    "deliveries": [
      {
        "channel": "email",
        "status": "opened",
        "destinationMasked": "m…a@example.cl"
      }
    ],
    "latestDecision": {
      "decision": "granted",
      "decidedAt": "2026-08-25T14:03:21.000Z",
      "captureMethod": "portal_link_otp"
    }
    // ... campos adicionales de la proyección
  }
}

Envíos de consentimiento

Eventos sobre los mensajes individuales (email, WhatsApp) con que se solicita el consentimiento.

{
  "event": "consent.delivery.failed",
  "sourceType": "consent_delivery",
  "sourceId": "7c1f00aa-2e43-4b7e-9f14-3d2e9a7c51d0",
  "occurredAt": "2026-08-25T09:12:44.008Z",
  "data": {
    "id": "7c1f00aa-2e43-4b7e-9f14-3d2e9a7c51d0",
    "consentRequestId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "channel": "whatsapp",
    "destinationMasked": "+569••••1234",
    "status": "failed",
    "failedAt": "2026-08-25T09:12:40.000Z",
    "failureReason": "Provider delivery failed."
    // ... campos adicionales de la fila de entrega
  }
}

Padrones compartidos

Eventos de la relación con los colegios y registradores que te comparten datos. Llegan sólo a tu espacio de trabajo y su data es una proyección propia ("projection": "partner_lifecycle"): ids, estados, fechas y nombres de organizaciones y grupos, nunca personas. Ver Registradores y solicitudes.

Conexiones

Derechos ARCO

Eventos sobre solicitudes de derechos. sourceType es rights_request y data trae la proyección completa de la solicitud tal como la ve la Consola. Ver Derechos ARCO.

{
  "event": "rights_request.created",
  "sourceType": "rights_request",
  "sourceId": "9e2a41d7-6c3b-4f0e-8a17-b5d4c2e8f901",
  "occurredAt": "2026-08-25T16:40:02.113Z",
  "data": {
    "id": "9e2a41d7-6c3b-4f0e-8a17-b5d4c2e8f901",
    "requestType": "access",
    "status": "received"
    // ... proyección completa de la solicitud
  }
}

Plazos ARCO

Eventos sobre el plazo legal de respuesta de una solicitud de derechos. Se emiten en el mismo barrido que envía el recordatorio por correo al equipo responsable; sourceType es rights_request y context trae stage y effectiveDueAt (la fecha vigente, con prórroga si la hubo).

Incidentes

Eventos sobre incidentes de seguridad y sus notificaciones a titulares.

{
  "event": "security.incident.created",
  "sourceType": "security_incident",
  "sourceId": "4f8b2c6d-1a0e-4d3f-9c7b-2e5a8d1f6b09",
  "occurredAt": "2026-08-25T18:05:37.902Z",
  "data": {
    "id": "4f8b2c6d-1a0e-4d3f-9c7b-2e5a8d1f6b09"
    // ... fila del incidente
  }
}

Payloads por sourceType

El contenido de data es la proyección del recurso de origen en el momento en que se construye la entrega (no en el momento del hecho: si el recurso cambió entre medio, verás su estado más reciente).

Proyección para partners (shared_partner)

En una campaña sobre un padrón compartido, la campaña vive en la organización del partner mientras la solicitud de consentimiento vive en la del sostenedor de los datos. Todo evento de consentimiento de esa solicitud (consent.requested, consent.decision.recorded, consent.revoked, consent.expired, consent.invalidated, consent.recaptured y los tres de envío) se emite para ambas partes con el mismo occurrenceKey:

• La copia del sostenedor lleva la proyección completa descrita arriba.
• La copia que reciben los endpoints de la organización del partner lleva una proyección reducida, construida como lista blanca campo a campo. Se identifica a sí misma con "projection": "shared_partner" para que nunca se confunda con una proyección completa a la que "le faltan" campos.

En la copia del partner, sourceType es siempre consent_request, también en los eventos de envío (el partner no tiene la fila de la entrega). Esos eventos agregan en context el id de la entrega (consentDeliveryId, el mismo de portalAccessLinks), deliveryChannel, deliveryStatus y, si falló, failureCode (destination_missing, dispatch_blocked o provider_failed), nunca el texto del proveedor ni el destino.

En una campaña segmentada por RUT el partner no recibe nada de una solicitud hasta que haya una decisión: un consent.requested le diría qué RUT están en el padrón, que es justo lo que ese modo protege.

La proyección reducida se limita a lo que el partner ya puede leer por su propio endpoint de sujetos compartidos: no incluye RUT (ni enmascarado), contactos en ninguna forma, el nombre del titular, el id interno del sujeto en la organización dueña, ni el contenido de la evidencia o texto libre de operadores. Sí trae el id y el checksum del manifiesto sellado (latestDecision.evidence), que no nombran a nadie y se validan en /api/public/evidence/verify. latestDecision.decisionAuthority indica el rol que decidió (titular, apoderado), nunca quién.

latestDecision.captureMethod dice cómo se capturó la decisión: portal_link_otp (la familia, con el enlace y el código de un solo uso) o registrar_attestation, el consentimiento declarado por el establecimiento mediante un registrador externo. Esta segunda no es una firma con código: su evidencia es una declaración jurada más la custodia del colegio, y tu integración debería mostrarla distinta. Los retiros que el registrador transmite llegan como consent.revoked con context.revocationSource: "registrar".

{
  "event": "consent.decision.recorded",
  "sourceType": "consent_request",
  "sourceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "occurredAt": "2026-08-25T14:03:22.511Z",
  "data": {
    "projection": "shared_partner",
    "consentRequestId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "dataOwnerOrganizationId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "registryShareId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "campaignId": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "campaignStatus": "active",
    "campaignMode": "per_subject",
    "campaignOrigin": "operator",
    "campaignContactEntryId": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
    "partnerExternalId": "par_04421",
    "processingActivityVersionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subject": {
      "referenceCode": "EST-04421",
      "subjectType": "student",
      "requestedForAgeBand": "under_14"
    },
    "status": "granted",
    "decisionActorType": "guardian",
    "requestedAt": "2026-08-20T12:00:00.000Z",
    "expiresAt": "2026-09-20T12:00:00.000Z",
    "updatedAt": "2026-08-25T14:03:21.000Z",
    "latestDecision": {
      "id": "0b8e4c2a-5d1f-4a6b-8c3e-7f9d2a1b6c4e",
      "decision": "granted",
      "decisionAuthority": "guardian",
      "captureMethod": "portal_link_otp",
      "decidedAt": "2026-08-25T14:03:21.000Z",
      "effectiveFrom": "2026-08-25T14:03:21.000Z",
      "effectiveTo": null,
      "revokedAt": null,
      "evidence": {
        "id": "…:manifest",
        "checksum": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
      }
    }
  }
}

campaignOrigin dice quién originó la campaña: operator (la lanzaste tú) o registrar_attestation (los consentimientos que un registrador externo declaró firmados; no se enviaron mensajes). Es null si la solicitud no pertenece a una campaña. campaignContactEntryId es el id del sobre y partnerExternalId tu correlativo, tal como lo mandaste al despachar. Cualquier otro sourceType en una copia de audiencia partner no tiene proyección aprobada, y por diseño no se divulga nada: data llega null.

Suscripción comodín

El valor almacenado ["*"] suscribe el endpoint a todos los eventos, incluidos los que se agreguen al catálogo en el futuro. El comodín debe ir solo: enabledEvents acepta ["*"] o una lista de tipos explícitos, nunca una mezcla. Si omites enabledEvents al crear el endpoint — o envías una lista vacía — el valor almacenado es ["*"].

Requisitos y garantías de entrega

• Solo HTTPS. La URL del endpoint debe usar https:// y no puede apuntar a hosts locales, direcciones privadas, link-local ni a la IP de metadatos de nube.
• Secreto de una sola vista. Si no envías un secreto al crear el endpoint, el servidor genera uno (whsec_…) y lo devuelve solo en esa respuesta. Puedes rotarlo cuando quieras; la rotación también lo devuelve una única vez.
• Reintentos. Una entrega se considera exitosa cuando tu endpoint responde con un estado 2xx. Si responde otra cosa o la conexión falla, el intento queda registrado como fallido y la cola vuelve a intentarlo; cada intento queda en el historial de entregas con su attemptNumber. Los destinos que ya recibieron con éxito una combinación (evento, origen, ocurrencia) no la vuelven a recibir en los reintentos.
• Idempotencia. Cada transición distinta de un mismo recurso viaja con su propia occurrenceKey interna, pero un reintento puede hacer que veas el mismo evento más de una vez. Deduplica por la tupla event + sourceId + el contenido relevante de data (por ejemplo, el status en los eventos de entrega) y responde 2xx rápido — procesa en segundo plano si tu trabajo es lento.
• Historial auditable. Cada intento queda en el registro de entregas del endpoint, consultable por la API de gestión: evento, origen, número de intento, estado y resumen del error (en un intento fallido, el resumen incluye el código con que respondió tu servidor). De la respuesta de tu servidor solo se conserva el código de estado, nunca el cuerpo.
• Módulo requerido. El despacho exige el módulo integrations activo en la licencia de la organización.
• Endpoints por conexión. Un endpoint puede quedar asociado a una conexión de partner mediante organizationPartnerConnectionId, para que el destino quede documentado junto a la relación que lo justifica.