Notificações sobre medidas de segurança

Use os webhooks de segurança e a API de consulta de casos de segurança para integrar os avisos sobre medidas de segurança da OpenAI aos fluxos de trabalho da sua equipe. Por exemplo, ao receber uma advertência, seu aplicativo pode consultar os detalhes do caso, identificar o usuário afetado e abrir um chamado para análise interna.

Quando usar esta integração

Use esta integração para:

• Encaminhar avisos de advertência e desativação à equipe de confiança e segurança ou à equipe de suporte.
• Adicionar informações do caso a um chamado de investigação ou suporte.
• Associar um aviso a um usuário por meio do mapeamento de identificadores de segurança do seu aplicativo.

As etapas deste guia usam uma advertência para ilustrar o fluxo de trabalho. Você pode usar a mesma integração para avisos de desativação.

Como funciona

Os webhooks de segurança notificam seu aplicativo quando a OpenAI emite um aviso.

Cada evento contém o ID de um caso. Use esse ID com GET /v1/safety/cases/{id} para consultar o identificador de segurança, o tipo de aviso, a data e a hora de criação do caso e, quando disponível, o motivo da medida segundo a política.

Essas notificações se aplicam à organização e são distintas dos alertas de desalinhamento, que se aplicam a cada projeto. Consultar um caso não altera nem reverte a medida aplicada.

Integração com seu aplicativo

Primeiro, configure um webhook no nível da organização e uma chave para consultar casos. Em seguida, integre as notificações ao seu fluxo de análise.

Configure o webhook e receba eventos

Use um identificador de segurança estável para cada usuário e mantenha no aplicativo um registro de qual usuário corresponde a cada identificador. Evite incluir informações pessoais no identificador.

Crie um endpoint de webhook no nível da organização nas configurações de webhooks da organização e assine os eventos safety.warning_issued e safety.deactivation_issued.

Uma notificação de advertência tem a seguinte estrutura:

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

Para conhecer as boas práticas gerais de uso de webhooks, consulte o guia de webhooks.

O campo id identifica o evento do webhook. O campo data.id identifica o caso de segurança a consultar.

Consulte o caso

Para consultar casos, configure uma chave de API da mesma organização com permissões Restricted e defina Safety como Read (api.safety.read).

Consulte os metadados do caso pela API de consulta de casos de segurança:

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

Uma consulta bem-sucedida retorna o código HTTP 200 e um objeto com os dados do caso. Por exemplo:

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

O campo entity_identifier representa o identificador de segurança afetado. A data e a hora de criação do caso podem ajudar na investigação. Consulte as definições dos campos na referência da API de casos de segurança.

Integre as notificações aos seus fluxos de trabalho

Use webhooks para receber notificações. Em seguida, use os metadados do caso para encaminhar os avisos de forma programática aos sistemas de investigação ou suporte que sua equipe já utiliza.

Solução de problemas