​

Webhooks

​

Ativar

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

• hooks.token é obrigatório quando hooks.enabled=true.
• hooks.path tem como padrão /hooks.

​

Autenticação

• Authorization: Bearer <token> (recomendado)
• x-openclaw-token: <token>
• Tokens de query-string são rejeitados (?token=... retorna 400).

​

Endpoints

​

POST /hooks/wake

{ "text": "System line", "mode": "now" }

• text obrigatório (string): A descrição do evento (por exemplo, “Novo e-mail recebido”).
• mode opcional (now | next-heartbeat): Se deve acionar um heartbeat imediato (padrão now) ou aguardar a próxima verificação periódica.

• Enfileira um evento de sistema para a sessão principal
• Se mode=now, aciona um heartbeat imediato

​

POST /hooks/agent

{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

• message obrigatório (string): O prompt ou mensagem para o agente processar.
• name opcional (string): Nome legível para humanos do hook (por exemplo, “GitHub”), usado como prefixo nos resumos de sessão.
• agentId opcional (string): direciona este hook para um agente específico. IDs desconhecidos retornam para o agente padrão. Quando definido, o hook é executado usando o workspace e a configuração do agente resolvido.
• sessionKey opcional (string): A chave usada para identificar a sessão do agente. Por padrão, este campo é rejeitado a menos que hooks.allowRequestSessionKey=true.
• wakeMode opcional (now | next-heartbeat): Se deve acionar um heartbeat imediato (padrão now) ou aguardar a próxima verificação periódica.
• deliver opcional (boolean): Se true, a resposta do agente será enviada ao canal de mensagens. O padrão é true. Respostas que são apenas reconhecimentos de heartbeat são automaticamente ignoradas.
• channel opcional (string): O canal de mensagens para entrega. Um de: last, whatsapp, telegram, discord, slack, mattermost (plugin), signal, imessage, msteams. O padrão é last.
• to opcional (string): O identificador do destinatário para o canal (por exemplo, número de telefone para WhatsApp/Signal, ID do chat para Telegram, ID do canal para Discord/Slack/Mattermost (plugin), ID da conversa para MS Teams). O padrão é o último destinatário na sessão principal.
• model opcional (string): Substituição de modelo (por exemplo, anthropic/claude-3-5-sonnet ou um alias). Deve estar na lista de modelos permitidos se houver restrição.
• thinking opcional (string): Substituição do nível de pensamento (por exemplo, low, medium, high).
• timeoutSeconds opcional (number): Duração máxima da execução do agente em segundos.

• Executa um turno de agente isolado (chave de sessão própria)
• Sempre publica um resumo na sessão principal
• Se wakeMode=now, aciona um heartbeat imediato

​

Política de session key (mudança incompatível)

• Recomendado: defina um hooks.defaultSessionKey fixo e mantenha desativados os overrides por requisição.
• Opcional: permita substituições na requisição apenas quando necessário e restrinja prefixos.

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // fortemente recomendado
  },
}

​

POST /hooks/<name> (mapeado)

• hooks.presets: ["gmail"] habilita o mapeamento integrado do Gmail.
• hooks.mappings permite definir match, action e templates na configuração.
• hooks.transformsDir + transform.module carrega um módulo JS/TS para lógica personalizada.
  • hooks.transformsDir (se definido) deve permanecer dentro do diretório raiz de transforms no diretório de configuração do OpenClaw (normalmente ~/.openclaw/hooks/transforms).
  • transform.module deve ser resolvido dentro do diretório efetivo de transforms (caminhos de travessia/escape são rejeitados).
• Use match.source para manter um endpoint genérico de ingestão (roteamento orientado por payload).
• Transformações em TS exigem um loader de TS (por exemplo, bun ou tsx) ou .js pré-compilado em tempo de execução.
• Defina deliver: true + channel/to nos mapeamentos para rotear respostas para uma superfície de chat (channel tem como padrão last e faz fallback para WhatsApp).
• agentId direciona o hook para um agente específico; IDs desconhecidos recorrem ao agente padrão.
• hooks.allowedAgentIds restringe o roteamento explícito por agentId. Omita (ou inclua *) para permitir qualquer agente. Defina [] para negar o roteamento explícito por agentId.
• hooks.defaultSessionKey define a sessão padrão para execuções do agente via hook quando nenhuma chave explícita é fornecida.
• hooks.allowRequestSessionKey controla se cargas de /hooks/agent podem definir sessionKey (padrão: false).
• hooks.allowedSessionKeyPrefixes opcionalmente restringe valores explícitos de sessionKey provenientes de cargas de requisição e mapeamentos.
• allowUnsafeExternalContent: true desativa o invólucro externo de segurança de conteúdo para esse hook (perigoso; apenas para fontes internas confiáveis).
• openclaw webhooks gmail setup grava configuração hooks.gmail para openclaw webhooks gmail run. Veja Gmail Pub/Sub para o fluxo completo de watch do Gmail.

​

Respostas

• 200 para /hooks/wake
• 202 para /hooks/agent (execução assíncrona iniciada)
• 401 em falha de autenticação
• 429 após falhas repetidas de autenticação do mesmo cliente (verifique Retry-After)
• 400 em payload inválido
• 413 em payloads grandes demais

​

Exemplos

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

​

Usar um modelo diferente

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

​

Segurança

• Mantenha endpoints de hook atrás de local loopback, tailnet ou um proxy reverso confiável.
• Use um token de hook dedicado; não reutilize tokens de autenticação do gateway.
• Falhas repetidas de autenticação são limitadas por taxa por endereço de cliente para desacelerar tentativas de força bruta.
• Se você usa roteamento multiagente, defina hooks.allowedAgentIds para limitar a seleção explícita de agentId.
• Mantenha hooks.allowRequestSessionKey=false a menos que precise de sessões selecionadas pelo solicitante.
• Se você habilitar sessionKey na requisição, restrinja hooks.allowedSessionKeyPrefixes (por exemplo, ["hook:"]).
• Evite incluir payloads brutos sensíveis nos logs de webhook.
• As cargas de gancho são tratadas como não confiáveis e dentro de limites de segurança por padrão. Payloads de hook são tratados como não confiáveis e envolvidos por limites de segurança por padrão. Se você precisar desativar isso para um hook específico, defina allowUnsafeExternalContent: true no mapeamento desse hook (perigoso).