Eventos webhook de Segurança e IAM

Visão geral

Os eventos webhook de segurança notificam seu SIEM ou ferramentas de monitoramento quando ações de IAM ocorrem no Gu1: ciclo de vida de membros, mudanças de perfis, login/logout, logins falhos, ações admin de senha e certas configurações de segurança. Configure-os como qualquer outro webhook em Configurações → Webhooks e inscreva-se apenas nos eventos security.* necessários.

Formato do payload (todos os eventos de segurança)

Cada webhook de segurança usa o envelope padrão mais um payload interno normalizado:

{
  "event": "security.auth.login_succeeded",
  "timestamp": "2026-06-18T12:00:00.000Z",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "actionAt": "2026-06-18T12:00:00.000Z",
    "actor": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "email": "admin@example.com",
      "displayName": "Jane Admin"
    },
    "affectedUser": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "email": "user@example.com",
      "displayName": "John User"
    },
    "description": "User logged in successfully",
    "changes": {
      "permissions": {
        "added": ["entities:write"],
        "removed": [],
        "current": ["entities:read", "entities:write"]
      }
    },
    "context": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 ...",
      "scope": "sandbox",
      "roleId": "uuid",
      "roleName": "Analyst"
    }
  }
}

Campo	Descrição
`actionAt`	Data/hora da ação (ISO 8601)
`actor`	Usuário que executou a ação (`id` = UUID na DB Gu1 quando disponível)
`affectedUser`	Usuário afetado (quando aplicável)
`description`	Resumo legível
`changes`	Mapa de campos alterados. Permissões de papel: `{ added, removed, current }`. Outros campos: `{ previous, current }`.
`context`	IP, user agent, escopo de settings, metadados de perfil

Eventos disponíveis

Membros (`security.member.*`)

Evento	Quando dispara
`security.member.invited`	Admin convida novo membro
`security.member.created`	Membro aceita convite / é criado na org
`security.member.removed`	Membro removido da organização
`security.member.activated`	Membro habilitado / reativado
`security.member.deactivated`	Membro desabilitado
`security.member.profile_updated`	Admin atualiza nome (`firstName` / `lastName`)
`security.member.password_reset`	Admin redefine senha do membro
`security.member.password_generated`	Admin gera senha temporária
`security.member.team_added`	Membro adicionado a uma equipe
`security.member.team_removed`	Membro removido de uma equipe
`security.member.team_role_changed`	Papel do membro dentro da equipe muda
`security.member.channel_granted`	Acesso concedido a um canal (org filha)
`security.member.channel_revoked`	Acesso revogado a um canal
`security.member.environment_granted`	Acesso concedido ao ambiente production ou sandbox
`security.member.environment_revoked`	Acesso revogado ao ambiente production ou sandbox
`security.member.environment_changed`	Um admin altera o acesso prod/sandbox de um membro em um único passo (`fromAccess` → `toAccess`)

context.teamType (ex.: production, sandbox) e context.teamRole aplicam-se a eventos de equipe. Para acesso a ambientes, context.environment é "production" ou "sandbox", com context.environmentOrganizationId e context.environmentOrganizationName. Em security.member.environment_changed, use context.fromAccess / context.toAccess ("both" | "production" | "sandbox" | "none") e changes.environmentAccess. Webhooks de canal disparam no contexto da org pai; context.channelOrganizationId identifica o canal.

Ciclo de convite (`security.member.invited` → `security.member.created`)

Se você assinar os dois eventos, espere duas entregas separadas nesta ordem:

Evento	Quando a Gu1 envia	`organizationId` no envelope
`security.member.invited`	Quando um admin envia o convite pela Gu1 (Equipes / fluxo de invite)	Organização onde o convite é emitido
`security.member.created`	Depois que o convidado conclui o cadastro e a membership é estabelecida nessa organização	Mesma organização do convite

O que o integrador deve esperar:

Não espere security.member.created no mesmo instante de security.member.invited. O convidado precisa aceitar primeiro; a entrega costuma ser segundos ou minutos depois.
Em security.member.created, actor e affectedUser em geral referem-se ao novo membro (mesmo UUID de usuário Gu1). affectedUser.email é o e-mail convidado.
payload.description normalmente é "Member accepted organization invitation". Em casos raros em que a configuração secundária (acesso ao sandbox pareado, papéis granulares ou atribuição a equipe) não pôde ser aplicada por completo no mesmo passo, a descrição pode ser "Member accepted organization invitation (environment sync incomplete)". O membro ainda tem acesso no contexto da organização do convite — trate o webhook como criação bem-sucedida do membro para SIEM e governança de acessos.
Se receber invited mas nunca created depois que o usuário confirmar que entrou na Gu1, verifique se seu endpoint respondeu HTTP 2xx em eventos próximos ao momento da aceitação e contate o suporte Gu1 com timestamp aproximado e organizationId.
Use payload.context.invitationId para correlacionar invited e created do mesmo convite (mesmo UUID nos dois eventos quando a aceitação for bem-sucedida).

Campos de context em convites (em security.member.invited e security.member.created quando aplicável):

Campo	Tipo	Descrição
`invitationId`	UUID	Registro de convite Gu1 — correlaciona invited → created
`granularRoleIds`	UUID[]	Papéis granulares para a org production
`granularRoleIdsSandbox`	UUID[]	Papéis granulares para a org sandbox pareada
`includeProduction`	boolean	O convite concede acesso a production
`includeSandbox`	boolean	O convite concede acesso a sandbox
`teamId`	UUID	Equipe production atribuída na aceitação
`teamIdSandbox`	UUID	Equipe sandbox atribuída na aceitação
`hasEnvironmentAccess`	boolean	Se o membro pode entrar naquele ambiente (`organization_members.has_environment_access`). Independente de papéis granulares e equipes, sempre provisionados conforme o convite em prod e sandbox quando definidos
`environment`	string	`"production"` ou `"sandbox"` conforme a org do envelope
`invitedByUserId`	UUID	Usuário Gu1 que enviou o convite
`acceptedVia`	string	Em `created`: `"invitation"` quando entrou por convite
`syncPartialFailure`	boolean	Apenas em `created`: configuração secundária (sandbox, papéis granulares, equipes) não concluída por completo
`syncErrorMessage`	string	Em `created` com `syncPartialFailure`: resumo interno do erro

Exemplo de payload security.member.invited:

{
  "event": "security.member.invited",
  "timestamp": "2026-06-18T12:00:00.000Z",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "actionAt": "2026-06-18T12:00:00.000Z",
    "actor": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "email": "admin@example.com",
      "displayName": "Jane Admin"
    },
    "affectedUser": {
      "email": "new@example.com"
    },
    "description": "User invited with role developer",
    "changes": {
      "role": { "previous": null, "current": "developer" }
    },
    "context": {
      "invitationId": "550e8400-e29b-41d4-a716-446655440099",
      "granularRoleIds": ["550e8400-e29b-41d4-a716-446655440011"],
      "granularRoleIdsSandbox": ["550e8400-e29b-41d4-a716-446655440012"],
      "includeProduction": true,
      "includeSandbox": true,
      "teamId": "550e8400-e29b-41d4-a716-446655440010",
      "teamIdSandbox": "550e8400-e29b-41d4-a716-446655440013",
      "hasEnvironmentAccess": true,
      "environment": "production",
      "invitedByUserId": "550e8400-e29b-41d4-a716-446655440001",
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 ..."
    }
  }
}

Exemplo de payload security.member.created:

{
  "event": "security.member.created",
  "timestamp": "2026-06-18T12:05:00.000Z",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "actionAt": "2026-06-18T12:05:00.000Z",
    "actor": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "email": "new@example.com"
    },
    "affectedUser": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "email": "new@example.com"
    },
    "description": "Member accepted organization invitation",
    "context": {
      "invitationId": "550e8400-e29b-41d4-a716-446655440099",
      "granularRoleIds": ["550e8400-e29b-41d4-a716-446655440011"],
      "granularRoleIdsSandbox": ["550e8400-e29b-41d4-a716-446655440012"],
      "includeProduction": true,
      "includeSandbox": true,
      "teamId": "550e8400-e29b-41d4-a716-446655440010",
      "hasEnvironmentAccess": true,
      "environment": "production",
      "acceptedVia": "invitation",
      "invitedByUserId": "550e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Eventos de acompanhamento relacionados (mesmo membro, webhooks separados quando aplicável): security.member.environment_granted, security.member.team_added, security.member.channel_granted, security.role.assigned.

Perfis e RBAC (`security.role.`, `security.rbac.`)

Evento	Quando dispara
`security.role.created`	Perfil granular criado
`security.role.updated`	Perfil modificado (inclui diff de permissões quando houver)
`security.role.deleted`	Perfil excluído
`security.role.assigned`	Perfil atribuído a usuário
`security.role.revoked`	Perfil revogado de usuário
`security.rbac.granular_toggled`	RBAC granular habilitado ou desabilitado

Autenticação (`security.auth.*`)

Evento	Quando dispara
`security.auth.login_succeeded`	Login bem-sucedido (web Gu1)
`security.auth.logout`	Logout
`security.auth.login_failed`	Tentativa falha (quando o e-mail resolve para uma org)

Configurações de segurança

Evento	Quando dispara
`security.settings.updated`	Modo sandbox, settings gerais/risco ou outras mudanças auditadas (`context.scope` indica a área)

Limitações

Não são cobertos hoje pelos webhooks de segurança Gu1:

Alteração de senha self-service do usuário no Clerk (somente IdP)
Mudanças MFA / SSO no Clerk
Autenticação API key M2M (distinta do login de usuário)
Revogações de sessão feitas apenas no dashboard Clerk

Reset/geração de senha por admin são cobertos via security.member.password_*.

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

AML Crypto

Serviços

Integrações

Tutoriais Interativos

Eventos webhook de Segurança e IAM

Visão geral

Formato do payload (todos os eventos de segurança)

Eventos disponíveis

Membros (`security.member.*`)

Ciclo de convite (`security.member.invited` → `security.member.created`)

Perfis e RBAC (`security.role.`, `security.rbac.`)

Autenticação (`security.auth.*`)

Configurações de segurança

Limitações

Relacionado

​Visão geral

​Formato do payload (todos os eventos de segurança)

​Eventos disponíveis

​Membros (security.member.*)

​Ciclo de convite (security.member.invited → security.member.created)

​Perfis e RBAC (security.role.*, security.rbac.*)

​Autenticação (security.auth.*)

​Configurações de segurança

​Limitações

​Relacionado

Visão geral

Formato do payload (todos os eventos de segurança)

Eventos disponíveis

Membros (`security.member.*`)

Ciclo de convite (`security.member.invited` → `security.member.created`)

Perfis e RBAC (`security.role.`, `security.rbac.`)

Autenticação (`security.auth.*`)

Configurações de segurança

Limitações

Relacionado