> ## Documentation Index > Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt > Use this file to discover all available pages before exploring further. # Eventos webhook de Segurança e IAM > Notificações em tempo real de autenticação, membros, perfis e configurações de segurança da Gu1 — para integrações SIEM e monitoramento de segurança. ## 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: ```json theme={null} { "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`: ```json theme={null} { "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`: ```json theme={null} { "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_*`. ## Relacionado * [Overview de webhooks](/pt/webhooks/overview) * [Segurança e assinaturas](/pt/webhooks/security) * [Configuração](/pt/webhooks/configuration)