Notificaciones sobre medidas de seguridad

Usa los webhooks de seguridad y la API de consulta de casos de seguridad para integrar los avisos sobre medidas de seguridad de OpenAI en los flujos de trabajo de tu equipo. Por ejemplo, cuando llega una advertencia, tu aplicación puede consultar los detalles del caso, identificar al usuario afectado y crear un ticket para revisión interna.

Cuándo usar esta integración

Usa esta integración para:

• Enviar avisos de advertencia y desactivación a tu equipo de confianza y seguridad o de soporte.
• Agregar información del caso a un ticket de investigación o soporte.
• Vincular un aviso con un usuario a partir de la relación que tu aplicación mantiene entre el usuario y su identificador de seguridad.

Los pasos de esta guía usan una advertencia como ejemplo del flujo de trabajo. Puedes usar la misma integración para los avisos de desactivación.

Cómo funciona

Los webhooks de seguridad notifican a tu aplicación cuando se emite un aviso.

Cada evento incluye el ID de un caso. Úsalo con GET /v1/safety/cases/{id} para obtener el identificador de seguridad, el tipo de aviso, la fecha y hora de creación del caso y, si está disponible, el motivo de la medida según la política.

Estas notificaciones se emiten a nivel de la organización y son independientes de las alertas de desalineación de cada proyecto. Consultar un caso no modifica ni revierte la medida aplicada.

Integra las notificaciones en tu aplicación

Primero, configura un webhook a nivel de la organización y una clave para consultar los casos. Luego, integra las notificaciones en tu flujo de revisión.

Configura el webhook y recibe eventos

Usa un identificador de seguridad estable para cada usuario y conserva en tu aplicación la relación entre cada identificador y el usuario correspondiente. Evita incluir información personal en el identificador.

Crea un punto de acceso de webhook a nivel de la organización en la configuración de webhooks de tu organización y suscríbete a safety.warning_issued y safety.deactivation_issued.

Una notificación de advertencia tiene la siguiente estructura:

123456789{
  "id": "evt_example",
  "object": "event",
  "created_at": 1787659200,
  "type": "safety.warning_issued",
  "data": {
    "id": "C-abc123"
  }
}

Para conocer las prácticas recomendadas para el uso de webhooks, consulta la guía de webhooks.

El campo id identifica el evento del webhook. El campo data.id identifica el caso de seguridad que debes consultar.

Consulta el caso

Para consultar casos, configura una clave de API de la misma organización con permisos Restricted y establece Safety en Read (api.safety.read).

Consulta los metadatos del caso mediante la API de consulta de casos de seguridad:

curl "https://api.openai.com/v1/safety/cases/C-abc123" \
  -H "Authorization: Bearer ${OPENAI_API_KEY}"

Si la consulta tiene éxito, la API devuelve el código HTTP 200 y un objeto con los datos del caso. Por ejemplo:

12345678910{
  "id": "C-abc123",
  "object": "safety.case",
  "created_at": 1787659100,
  "entity_identifier": "entity_identifier",
  "reason": "cyber_abuse",
  "notice": {
    "type": "warning"
  }
}

El campo entity_identifier representa el identificador de seguridad afectado. La fecha y hora de creación del caso pueden ser útiles para la investigación. Consulta las definiciones de los campos en la referencia de la API de casos de seguridad.

Integra los avisos en tus flujos de trabajo

Usa webhooks para recibir las notificaciones. Luego, usa los metadatos de cada caso para dirigir los avisos mediante código a los sistemas de investigación o soporte que ya utilizas.

Solución de problemas