Gestión de webhooks

Esta página cubre la API con que administras los endpoints de webhook de tu organización: crearlos, listarlos con su historial de entregas, actualizarlos, activarlos o desactivarlos, rotar su secreto y eliminarlos. El formato de las entregas, la firma y el catálogo de eventos están en la guía de webhooks.

Las rutas aceptan sesión de la Consola o una API key de organización en la cabecera x-api-key. Las lecturas exigen el permiso integrations.read; las escrituras, integrations.write. Todo lo descrito aquí también está disponible en la Consola, en Integraciones → Webhooks.

El modelo de endpoint

Las respuestas devuelven el endpoint en su forma segura: nunca incluyen el secreto almacenado (solo el indicador hasSecret); el secreto en texto plano aparece únicamente en las respuestas de creación y de rotación.

Propiedades

Nombre
id
Tipo
string
Descripción
Identificador único del endpoint.
Nombre
name
Tipo
string
Descripción
Nombre del endpoint, único dentro de la organización.
Nombre
endpointUrl
Tipo
string
Descripción
URL de destino. Solo https://; se rechazan hosts locales, direcciones privadas, link-local y la IP de metadatos de nube (OUTBOUND_WEBHOOK_URL_BLOCKED).
Nombre
enabledEvents
Tipo
array de strings
Descripción
Eventos suscritos, o ["*"] para todos (incluidos los futuros). El comodín debe ir solo en el arreglo.
Nombre
signatureHeader
Tipo
string
Descripción
Nombre de la cabecera donde viaja la firma. Se almacena en minúsculas; por defecto x-edugoverna-signature.
Nombre
authType
Tipo
string
Descripción
Esquema de autenticación de las entregas. Por defecto hmac_sha256.
Nombre
status
Tipo
string
Descripción
active o disabled. Un endpoint desactivado no recibe entregas.
Nombre
organizationPartnerConnectionId
Tipo
string | null
Descripción
Conexión de partner a la que está asociado el endpoint, si corresponde.
Nombre
hasSecret
Tipo
boolean
Descripción
Indica que el endpoint tiene un secreto configurado.
Nombre
lastSuccessAt
Tipo
timestamp
Descripción
Última entrega exitosa.
Nombre
lastFailureAt
Tipo
timestamp
Descripción
Última entrega fallida.
Nombre
metadata
Tipo
object | null
Descripción
Metadatos libres definidos al crear el endpoint.

GET/api/integrations/webhook-endpoints

Listar los endpoints

Devuelve todos los endpoints de webhook de la organización, en su forma segura.

Solicitud

GET

/api/integrations/webhook-endpoints

curl https://app.edugoverna.com/api/integrations/webhook-endpoints \
  -H "x-api-key: {api_key}"

Respuesta

{
  "webhookEndpoints": [
    {
      "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
      "name": "erp-colegio",
      "endpointUrl": "https://erp.micolegio.cl/webhooks/edugoverna",
      "enabledEvents": ["*"],
      "signatureHeader": "x-edugoverna-signature",
      "authType": "hmac_sha256",
      "status": "active",
      "organizationPartnerConnectionId": null,
      "hasSecret": true,
      "lastSuccessAt": "2026-08-25T14:03:22.511Z",
      "lastFailureAt": null,
      "metadata": null
    }
  ]
}

POST/api/integrations/webhook-endpoints

Crear un endpoint

Registra un endpoint nuevo. La respuesta 201 incluye el campo secret — el secreto en texto plano — una única vez; después de esta respuesta solo podrás rotarlo.

Atributos obligatorios

Nombre
name
Tipo
string
Descripción
Nombre del endpoint (2–120 caracteres). Debe ser único en la organización; un nombre repetido responde 409 con OUTBOUND_WEBHOOK_NAME_TAKEN.
Nombre
endpointUrl
Tipo
string
Descripción
URL de destino, solo https://.

Atributos opcionales

Nombre
secret
Tipo
string
Descripción
Secreto propio (10–500 caracteres). Si lo omites, el servidor genera uno con prefijo whsec_ y lo devuelve en esta respuesta.
Nombre
enabledEvents
Tipo
array de strings
Descripción
Eventos a suscribir. ["*"] suscribe todos los eventos, actuales y futuros, y debe ir solo en el arreglo — mezclar el comodín con tipos explícitos es un error de validación. Si omites el campo — o envías una lista vacía — el valor almacenado es ["*"].
Nombre
signatureHeader
Tipo
string
Descripción
Nombre de la cabecera de firma (2–120 caracteres). Se normaliza a minúsculas. Por defecto x-edugoverna-signature.
Nombre
organizationPartnerConnectionId
Tipo
string
Descripción
UUID de una conexión de partner de tu organización, para asociar el endpoint a esa relación. Una conexión inexistente responde 404 con OUTBOUND_WEBHOOK_CONNECTION_NOT_FOUND.
Nombre
authType
Tipo
string
Descripción
Esquema de autenticación. Por defecto hmac_sha256.
Nombre
status
Tipo
string
Descripción
Estado inicial. Por defecto active.
Nombre
metadata
Tipo
object
Descripción
Metadatos libres.

Solicitud

POST

/api/integrations/webhook-endpoints

curl https://app.edugoverna.com/api/integrations/webhook-endpoints \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp-colegio",
    "endpointUrl": "https://erp.micolegio.cl/webhooks/edugoverna",
    "enabledEvents": [
      "consent.decision.recorded",
      "consent.revoked",
      "rights_request.created"
    ]
  }'

Respuesta (201)

{
  "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
  "name": "erp-colegio",
  "endpointUrl": "https://erp.micolegio.cl/webhooks/edugoverna",
  "enabledEvents": [
    "consent.decision.recorded",
    "consent.revoked",
    "rights_request.created"
  ],
  "signatureHeader": "x-edugoverna-signature",
  "authType": "hmac_sha256",
  "status": "active",
  "hasSecret": true,
  "secret": "whsec_f47ac10b58cc4372a5670e02b2c3d479"
}

GET/api/integrations/webhook-endpoints/:id

Consultar un endpoint

Devuelve un endpoint junto con sus intentos de entrega más recientes (hasta 50, del más nuevo al más antiguo) y estadísticas agregadas. Es la herramienta principal para diagnosticar entregas fallidas.

Cada entrega del historial trae:

Nombre
eventType
Tipo
string
Descripción
El evento entregado.
Nombre
sourceType
Tipo
string
Descripción
Tipo del recurso de origen.
Nombre
sourceId
Tipo
string
Descripción
Identificador del recurso de origen.
Nombre
attemptNumber
Tipo
integer
Descripción
Número del intento (los reintentos incrementan este valor).
Nombre
status
Tipo
string
Descripción
delivered o failed.
Nombre
responseCode
Tipo
integer | null
Descripción
Código HTTP con que respondió tu servidor, si quedó registrado; hoy llega null y, en los intentos fallidos, el código viaja dentro de errorSummary.
Nombre
deliveredAt
Tipo
timestamp | null
Descripción
Cuándo se confirmó la entrega.
Nombre
errorSummary
Tipo
string | null
Descripción
Resumen del error del intento fallido, por ejemplo Webhook responded 500.

Solicitud

GET

/api/integrations/webhook-endpoints/:id

curl https://app.edugoverna.com/api/integrations/webhook-endpoints/886313e1-3b8a-5372-9b90-0c9aee199e5d \
  -H "x-api-key: {api_key}"

Respuesta

{
  "endpoint": {
    "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
    "name": "erp-colegio",
    "status": "active"
    // ... resto del endpoint
  },
  "deliveries": [
    {
      "id": "b1946ac9-2d5a-4a3c-8f2e-0d9c7e6f5a4b",
      "eventType": "consent.decision.recorded",
      "sourceType": "consent_request",
      "sourceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "attemptNumber": 1,
      "status": "delivered",
      "responseCode": null,
      "deliveredAt": "2026-08-25T14:03:22.511Z",
      "nextRetryAt": null,
      "errorSummary": null,
      "createdAt": "2026-08-25T14:03:22.300Z"
    }
  ],
  "stats": { "total": 1, "ok": 1, "failed": 0 }
}

PATCH/api/integrations/webhook-endpoints/:id

Actualizar un endpoint

Actualiza el nombre, la URL o la lista de eventos suscritos. Debes enviar al menos uno de los tres campos; los que omitas no cambian. La URL nueva pasa por la misma validación https/anti-SSRF que en la creación, y el nombre nuevo por la misma regla de unicidad.

Atributos opcionales

Nombre
name
Tipo
string
Descripción
Nuevo nombre (2–120 caracteres).
Nombre
endpointUrl
Tipo
string
Descripción
Nueva URL de destino, solo https://.
Nombre
enabledEvents
Tipo
array de strings
Descripción
Nueva lista de eventos; reemplaza la lista completa. Rige la misma regla del comodín ["*"], y una lista vacía vuelve al comodín.

Solicitud

PATCH

/api/integrations/webhook-endpoints/:id

curl -X PATCH https://app.edugoverna.com/api/integrations/webhook-endpoints/886313e1-3b8a-5372-9b90-0c9aee199e5d \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "enabledEvents": ["*"] }'

Respuesta

{
  "webhookEndpoint": {
    "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
    "enabledEvents": ["*"]
    // ... resto del endpoint
  }
}

POST/api/integrations/webhook-endpoints/:id/status

Activar o desactivar

Cambia el estado del endpoint. Un endpoint disabled conserva su configuración y su historial, pero deja de recibir entregas hasta que lo reactives.

Atributos obligatorios

Nombre
status
Tipo
string
Descripción
active o disabled.

Solicitud

POST

/api/integrations/webhook-endpoints/:id/status

curl -X POST https://app.edugoverna.com/api/integrations/webhook-endpoints/886313e1-3b8a-5372-9b90-0c9aee199e5d/status \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Respuesta

{
  "webhookEndpoint": {
    "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
    "status": "disabled"
    // ... resto del endpoint
  }
}

POST/api/integrations/webhook-endpoints/:id/rotate-secret

Rotar el secreto

Genera un secreto nuevo (whsec_…) y lo devuelve una única vez en el campo secret de la respuesta. El secreto anterior deja de ser válido de inmediato: las entregas siguientes se firman solo con el nuevo, así que actualiza tu verificador antes o inmediatamente después de rotar.

Solicitud

POST

/api/integrations/webhook-endpoints/:id/rotate-secret

curl -X POST https://app.edugoverna.com/api/integrations/webhook-endpoints/886313e1-3b8a-5372-9b90-0c9aee199e5d/rotate-secret \
  -H "x-api-key: {api_key}"

Respuesta

{
  "webhookEndpoint": {
    "id": "886313e1-3b8a-5372-9b90-0c9aee199e5d",
    "hasSecret": true,
    "secret": "whsec_a3bb189e8bf938889912ace4e6543002"
    // ... resto del endpoint
  }
}

DELETE/api/integrations/webhook-endpoints/:id

Eliminar un endpoint

Elimina el endpoint y todo su historial de entregas. La operación es permanente; si solo quieres pausar las entregas, usa Activar o desactivar.

Solicitud

DELETE

/api/integrations/webhook-endpoints/:id

curl -X DELETE https://app.edugoverna.com/api/integrations/webhook-endpoints/886313e1-3b8a-5372-9b90-0c9aee199e5d \
  -H "x-api-key: {api_key}"

Respuesta

{
  "deleted": true
}