---
title: "Automação Avançada — Webhooks e Cron Jobs"
url: "https://openclaw.ia.br/guias/automacao-avancada/"
markdown_url: "https://openclaw.ia.br/guias/automacao-avancada.MD"
description: "Técnicas avançadas de automação no OpenClaw. Webhooks, cron jobs, pipelines e workflows complexos."
date: ""
author: ""
---

# Automação Avançada — Webhooks e Cron Jobs

Técnicas avançadas de automação no OpenClaw. Webhooks, cron jobs, pipelines e workflows complexos.


# Automação Avançada com OpenClaw

## Introdução

Quando você domina os comandos básicos do OpenClaw, o próximo nível é criar automações que funcionam sem nenhuma intervenção manual. Webhooks, cron jobs e pipelines transformam seu assistente de IA em um sistema que age proativamente — respondendo a eventos externos, executando tarefas em horários programados e orquestrando fluxos de trabalho complexos de ponta a ponta.

Este guia é para quem já usa o OpenClaw no dia a dia e quer extrair o máximo da plataforma. Você vai aprender a configurar webhooks para integrar com GitHub, Stripe, formulários web e outras ferramentas; criar pipelines de processamento de conteúdo; orquestrar múltiplos agentes especializados; e conectar o OpenClaw a ferramentas de automação visual como n8n e Zapier.

A automação avançada pode parecer complexa no início, mas o retorno é enorme. Uma vez configurado, um pipeline de automação trabalha 24 horas por dia, 7 dias por semana, sem custo adicional de mão de obra. Um usuário que passa 2 horas configurando uma automação pode economizar horas de trabalho manual por semana.

## Pré-requisitos

Para aproveitar este guia ao máximo, você precisa de:

- OpenClaw instalado e configurado com pelo menos um canal ativo
- Familiaridade com o arquivo `config.yaml` e arquivos SOUL.md/MEMORY.md
- Servidor com acesso público à internet (para webhooks receberem chamadas externas)
- Conhecimento básico de YAML e, opcionalmente, JavaScript/shell scripting
- [Heartbeats configurados](/guias/pos-instalacao/) (base para automações temporais)

## Webhooks — Recebendo Eventos Externos

Webhooks são URLs que o OpenClaw expõe para receber notificações de serviços externos. Quando algo acontece no GitHub, Stripe, Typeform ou qualquer outro serviço, eles chamam a URL do seu webhook e o OpenClaw processa o evento automaticamente.

### Configurando o Servidor de Webhooks

Primeiro, ative o servidor de webhooks no `config.yaml`:

```yaml
webhooks:
  enabled: true
  port: 3435
  path: /webhooks
  secret: ${WEBHOOK_SECRET}  # Segredo para validar autenticidade
```

Gere um secret seguro:

```bash
openssl rand -hex 32
# Copie o resultado para a variável WEBHOOK_SECRET
export WEBHOOK_SECRET="seu-secret-gerado-aqui"
```

### Webhook do GitHub

Automatize seu fluxo de desenvolvimento recebendo eventos do GitHub:

```yaml
webhooks:
  handlers:
    - name: github-push
      path: /webhooks/github
      secret: ${GITHUB_WEBHOOK_SECRET}
      events:
        - push
        - pull_request
        - issues
      action: |
        Analise o evento GitHub recebido.
        Para push: resuma as mudanças e notifique no canal #dev do Slack.
        Para pull_request aberto: atribua reviewers baseado nos arquivos modificados.
        Para issues: categorize e adicione labels apropriadas.
```

No GitHub, vá em **Settings > Webhooks > Add webhook** e configure:
- Payload URL: `https://seuservidor.com/webhooks/github`
- Content type: `application/json`
- Secret: o mesmo que você configurou
- Events: escolha os eventos que quer receber

```bash
# Testar webhook localmente com ngrok
ngrok http 3435
# Use a URL gerada como Payload URL no GitHub
```

### Webhook de Pagamentos (Stripe)

Automatize ações pós-pagamento:

```yaml
webhooks:
  handlers:
    - name: stripe-events
      path: /webhooks/stripe
      events:
        - payment_intent.succeeded
        - customer.subscription.created
        - invoice.payment_failed
      action: |
        Para pagamento aprovado:
          1. Envie email de boas-vindas via Gmail
          2. Crie registro no banco de dados
          3. Notifique equipe de vendas no Telegram
        Para pagamento falho:
          1. Envie email de alerta ao cliente
          2. Crie ticket de suporte
```

### Webhook de Formulários

Processe submissões de formulários automaticamente:

```yaml
webhooks:
  handlers:
    - name: typeform-leads
      path: /webhooks/forms/contato
      action: |
        Recebeu novo lead do formulário de contato.
        1. Extraia nome, email e mensagem do payload
        2. Categorize o tipo de interesse (suporte, vendas, parceria)
        3. Adicione ao CRM via API
        4. Envie resposta personalizada por email
        5. Notifique o responsável pela categoria no WhatsApp
```

## Pipelines de Processamento

Pipelines são sequências de etapas que processam dados de forma automatizada. No OpenClaw, você define o fluxo e o agente executa cada etapa.

### Pipeline de Conteúdo

Automatize a criação e publicação de conteúdo:

```yaml
pipelines:
  content-creation:
    trigger: schedule
    cron: "0 8 * * 1"  # Segunda-feira às 8h
    steps:
      - name: research
        prompt: |
          Pesquise as 5 principais tendências em [seu setor] desta semana.
          Fontes: Google Trends, Twitter/X, principais blogs do setor.
          Formato: JSON com título, resumo e URL de cada tendência.

      - name: select-topic
        prompt: |
          Com base nas tendências pesquisadas, selecione a mais relevante
          para nosso público (PMEs brasileiras). Justifique a escolha.

      - name: write-article
        prompt: |
          Escreva um artigo de 800 palavras sobre o tópico selecionado.
          Tom: profissional mas acessível.
          Inclua: introdução, 3 seções principais, conclusão com CTA.
          Formato: Markdown.

      - name: review
        prompt: |
          Revise o artigo. Verifique: gramática, clareza, coerência,
          aderência ao tom da marca. Faça correções necessárias.

      - name: publish
        prompt: |
          Publique o artigo no WordPress via API.
          Adicione tags e categoria relevantes.
          Compartilhe no LinkedIn e Twitter com copy atraente.
```

### Pipeline de Análise de Dados

Processe e analise dados automaticamente:

```yaml
pipelines:
  weekly-report:
    trigger: schedule
    cron: "0 9 * * 5"  # Sexta-feira às 9h
    steps:
      - name: fetch-data
        action: fetch-analytics
        params:
          period: last_7_days
          metrics: ["sessions", "conversions", "revenue"]

      - name: analyze
        prompt: |
          Analise os dados da semana. Identifique:
          - Tendências positivas e negativas
          - Anomalias que precisam de atenção
          - Comparação com semana anterior
          - Top 3 recomendações de ação

      - name: report
        prompt: |
          Crie relatório executivo em formato de email.
          Máximo 300 palavras. Inclua os principais números
          e as 3 recomendações prioritárias.

      - name: send
        action: send-email
        params:
          to: ["equipe@empresa.com", "ceo@empresa.com"]
          subject: "Relatório Semanal — {data_atual}"
```

## Integração com n8n e Zapier

### Usando o OpenClaw como Action no n8n

O n8n é uma ferramenta de automação open-source que você pode hospedar. Para conectar ao OpenClaw:

1. No n8n, adicione um nó **HTTP Request**
2. Configure:
   - Method: `POST`
   - URL: `http://localhost:3434/api/message`
   - Authentication: Bearer Token (use sua API key interna)
   - Body:
   ```json
   {
     "channel": "internal",
     "message": "{{$node.trigger.json.text}}"
   }
   ```

3. O OpenClaw processa e retorna a resposta no corpo da requisição

**Exemplo de workflow n8n:**
```
[Gmail Trigger] → [Filtrar urgentes] → [OpenClaw] → [Criar task no Asana]
```

### Usando como Action no Zapier

Para Zapier:

1. Use o action **Webhooks by Zapier**
2. Configure:
   - URL: `https://seuservidor.com/api/message`
   - Payload type: JSON
   - Data: `{"channel": "internal", "message": "{{dados do trigger}}"}`

**Exemplo de workflow Zapier:**
```
[Typeform] → [OpenClaw analisa e qualifica] → [HubSpot CRM]
```

## Orquestração de Múltiplos Agentes

Para tarefas complexas, você pode criar uma arquitetura com agentes especializados:

```yaml
agents:
  main:
    model: claude-sonnet-4
    role: orchestrator
    description: "Coordena os outros agentes e toma decisões de alto nível"

  researcher:
    model: claude-haiku-3-5
    role: specialist
    description: "Especialista em pesquisa e coleta de informações"
    tools: ["web_search", "read_url"]

  writer:
    model: claude-sonnet-4
    role: specialist
    description: "Especialista em criação de conteúdo"
    tools: ["write_file"]

  reviewer:
    model: claude-opus-4
    role: specialist
    description: "Revisão crítica de alta qualidade"
```

O agente principal coordena:

```
Main Agent recebe: "Crie artigo sobre tendências de IA em 2026"
  ↓
Researcher Agent: pesquisa fontes, coleta dados
  ↓
Writer Agent: cria primeiro rascunho
  ↓
Reviewer Agent: revisa e sugere melhorias
  ↓
Writer Agent: aplica correções
  ↓
Main Agent: aprova e publica
```

### Exemplo Prático: Deploy Automatizado

```yaml
pipelines:
  auto-deploy:
    trigger: webhook
    path: /webhooks/github
    filter: "event == 'push' && branch == 'main'"
    steps:
      - name: analyze-diff
        prompt: |
          Analise o diff do commit. Identifique:
          - Tipo de mudança (feature, bugfix, refactor)
          - Risco estimado (baixo/médio/alto)
          - Serviços afetados

      - name: run-tests
        action: shell
        command: "cd /app && npm test"
        on_failure: notify_team

      - name: deploy
        condition: "risk == 'baixo' && tests == 'passed'"
        action: shell
        command: "cd /app && ./deploy.sh production"

      - name: notify
        prompt: |
          Compose mensagem de notificação para o Telegram:
          Deploy realizado com sucesso.
          Versão: {commit_hash}
          Mudanças: {resumo_do_diff}
          Tempo: {duration}
```

## Configuração Avançada

### Rate Limiting e Controle de Fluxo

Evite sobrecarregar as APIs:

```yaml
automation:
  rateLimit:
    requestsPerMinute: 10
    retryOnLimit: true
    retryDelay: 60
    maxRetries: 3

  queue:
    enabled: true
    maxConcurrent: 3
    priorityLevels:
      high: ["emergency", "payment"]
      normal: ["content", "report"]
      low: ["cleanup", "archive"]
```

### Error Handling e Rollback

Configure o que acontece quando algo falha:

```yaml
pipelines:
  content-creation:
    errorHandling:
      onStepFailure: pause  # pause, skip, abort
      notifyOnFailure: true
      notifyChannel: telegram
      maxRetries: 2

    rollback:
      enabled: true
      keepLastN: 5  # Mantém 5 versões para rollback
```

### Logs e Monitoramento de Automações

```bash
# Ver logs de automações em tempo real
openclaw automation logs --follow

# Status de todos os pipelines ativos
openclaw automation status

# Histórico de execuções
openclaw automation history --last 50

# Métricas de performance
openclaw automation metrics --period 7d
```

## Erros Comuns e Soluções

| Erro | Causa Provável | Solução |
|------|----------------|---------|
| Webhook não recebe eventos | Servidor sem IP público ou firewall bloqueando | Verifique se a porta está aberta: `curl http://seuip:3435/health` |
| Pipeline para no meio | Timeout ou erro na API de IA | Aumente `stepTimeout` e configure `maxRetries` |
| Agentes em loop infinito | Prompt ambíguo ou condição de saída mal definida | Adicione limite de iterações: `maxIterations: 10` |
| Webhooks duplicados | Múltiplas instâncias processando o mesmo evento | Use `idempotencyKey` para deduplificação |
| Custo explodindo com automações | Muitas requisições para modelos caros | Use Haiku para etapas simples, Sonnet apenas onde necessário |
| Credenciais expiradas em webhooks | Token de serviço externo venceu | Configure renovação automática de tokens |

## Boas Práticas

- **Comece simples:** Antes de criar pipelines complexos com 10 etapas, valide o conceito com 2-3 etapas. Adicione complexidade incrementalmente quando o básico estiver funcionando.

- **Idempotência:** Designe suas automações para funcionar corretamente mesmo se executadas múltiplas vezes com o mesmo input. Use IDs únicos e verificações de duplicidade, especialmente em webhooks.

- **Defina critérios de parada:** Todo pipeline precisa de condições claras de sucesso e falha. Sem isso, um erro pode fazer o agente ficar tentando indefinidamente.

- **Logs detalhados:** Em produção, log tudo. Quando algo der errado às 3h da manhã, você vai precisar de informações suficientes para diagnosticar sem recriar o problema.

- **Ambiente de teste separado:** Antes de ativar webhooks em produção, teste com ngrok ou um ambiente de staging. Erros em webhooks podem se propagar rapidamente.

- **Limites de gasto por pipeline:** Configure limites de custo específicos para automações longas. Um loop acidental pode consumir centenas de dólares em tokens antes que você perceba.

- **Notificações de falha:** Configure alertas quando automações falham. Você quer saber que o relatório semanal não foi gerado antes que seu chefe pergunte onde está.

- **Revisão humana para ações críticas:** Use human-in-the-loop para automações que envolvem publicar conteúdo público, enviar emails em massa ou fazer deploys. Um checkpoint humano pode prevenir desastres.

## Perguntas Frequentes

**Como testar webhooks localmente sem deploy?**
Use o ngrok: `ngrok http 3435`. Ele cria um túnel público para a porta 3435 do seu computador. Use a URL gerada nos serviços externos durante o desenvolvimento. Lembre de que a URL muda a cada sessão do ngrok na versão gratuita.

**Posso ter múltiplos pipelines rodando simultaneamente?**
Sim, o OpenClaw suporta execução paralela de pipelines. Configure o limite de concorrência em `automation.queue.maxConcurrent` para evitar sobrecarregar as APIs. O padrão é 3 pipelines simultâneos.

**Como debugar um pipeline que trava no meio?**
Use o comando `openclaw automation logs --pipeline nome-do-pipeline --follow` para acompanhar em tempo real. Para pipelines que travaram, `openclaw automation inspect --id ID-DO-PIPELINE` mostra o estado interno de cada etapa.

**É possível criar pipelines condicionais (if/else)?**
Sim, usando o campo `condition` em cada etapa. Exemplo: `condition: "previous.output.risk == 'baixo'"`. O OpenClaw usa uma linguagem de expressão simples para condições.

**Como compartilhar pipelines com a equipe?**
Pipelines são definidos em YAML e podem ser versionados no Git como qualquer código. Crie um repositório de "automações da empresa" e faça deploy nas instâncias de cada pessoa. Consulte o [guia de uso em equipe](/guias/equipe/) para mais detalhes.

## Próximos Passos

- [Guia de Equipes](/guias/equipe/) — Compartilhe automações entre membros
- [Debugging e Logs](/guias/debugging/) — Diagnose problemas em pipelines
- [Performance](/guias/performance/) — Otimize velocidade e custo das automações
- [Receitas Prontas](/receitas/) — Pipelines pré-configurados para casos comuns
- [Canais de Integração](/canais/) — Conecte o OpenClaw a mais serviços
- [Glossário: Webhooks](/glossario/webhook/) — Entenda o conceito em detalhes