100monkeys.ai

Blog · Guia · 29 de outubro de 2026

Inicie um workflow do AEGIS a partir de um webhook assinado

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: a 100monkeys.ai desenvolve o AEGIS, então leia este guia como o relato de quem o fabrica. Ele foi redigido por um dos nossos agentes de IA a partir da documentação pública do AEGIS, Configuring Webhooks, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Cada comando e bloco de código abaixo foi copiado dessa página, e nenhum foi executado para este guia. As citações ficam em inglês com a tradução ao lado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

AEGIS by 100monkeys.ai, in beta, pode iniciar um workflow quando outro sistema lhe envia um evento: um push no GitHub, um job de CI que termina, qualquer serviço capaz de fazer uma requisição HTTP. O emissor não precisa de conta no seu nó. Nas palavras da documentação, "Authentication is handled by HMAC-SHA256 signature verification, not OAuth." (a autenticação é feita pela verificação de uma assinatura HMAC-SHA256, não por OAuth). Este guia configura uma origem de ponta a ponta, do segredo compartilhado a uma requisição testada, e cobre os erros que você vai encontrar no caminho.

Passo 1. Dê nome à origem

Todo webhook chega em POST /v1/webhooks/{source}. A origem é "a lowercase slug that identifies the system sending the event" (um slug em minúsculas que identifica o sistema que envia o evento), como github, stripe ou my-ci. Escolha uma por sistema emissor: o segredo, a rota e a checagem de duplicatas dependem dela.

Passo 2. Defina o segredo compartilhado no orquestrador

Os segredos valem por tenant e origem, então dois tenants que chamam a própria origem de github têm "completely independent secrets" (segredos completamente independentes). Cada par é uma variável de ambiente no orquestrador, com nome neste padrão:

# Pattern: AEGIS_WEBHOOK_SECRET_<UPPER_TENANT>_<UPPER_SOURCE>
# Hyphens and dots in tenant id and source name are replaced with underscores

export AEGIS_WEBHOOK_SECRET_U_ABC123_GITHUB="your-shared-secret-here"
export AEGIS_WEBHOOK_SECRET_U_ABC123_STRIPE="another-secret"
export AEGIS_WEBHOOK_SECRET_U_DEF456_MY_CI="third-secret"

Assim, o tenant u-abc123 com a origem my-ci lê AEGIS_WEBHOOK_SECRET_U_ABC123_MY_CI. Se a variável do par resolvido não existir, a requisição é rejeitada com 401 secret_not_found. Dê o mesmo segredo ao emissor e a mais ninguém.

Passo 3. Roteie a origem para um workflow

Uma rota direta liga a origem a um workflow, de modo que o roteamento é "instant and deterministic" (instantâneo e determinístico). Na versão atual, as rotas diretas são "configured via orchestrator workflow routing configuration" (configuradas pela configuração de roteamento de workflows do orquestrador), e a página observa que "there is no aegis stimulus routes CLI command yet" (ainda não existe o comando de CLI aegis stimulus routes). Sem rota direta, o pipeline recorre a um RouterAgent configurado, que classifica o evento com um modelo de linguagem. Sem nenhum dos dois, a requisição falha com 422 no_router_configured. Para um único emissor conhecido, a rota direta é a que convém: o mesmo evento sempre inicia o mesmo workflow.

Passo 4. Assine o corpo bruto no emissor

O emissor calcula um HMAC-SHA256 do corpo bruto da requisição com o segredo compartilhado e o envia em X-Aegis-Signature com o prefixo sha256=. O exemplo em Python da documentação:

import hashlib
import hmac
import json
import requests

def sign_payload(body: bytes, secret: str) -> str:
    sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return f"sha256={sig}"

payload = json.dumps({"event": "push", "ref": "refs/heads/main"}).encode()
signature = sign_payload(payload, WEBHOOK_SECRET)

requests.post(
    "https://your-aegis-node/v1/webhooks/github",
    data=payload,
    headers={
        "Content-Type": "application/json",
        "X-Aegis-Signature": signature,
    },
)

A página traz o mesmo em Node.js. A regra que ela põe em negrito: calcule o HMAC sobre os bytes brutos do corpo antes de qualquer parsing, porque "Computing over a re-serialized object will produce a different signature." (calcular sobre um objeto reserializado produz uma assinatura diferente). Assine exatamente os bytes que você envia.

Passo 5. Teste o endpoint com curl

# Generate a test signature
SECRET="your-shared-secret-here"
BODY='{"event":"push","ref":"refs/heads/main"}'
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"

# Send the test webhook
curl -X POST https://your-aegis-node/v1/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-Aegis-Signature: $SIG" \
  -d "$BODY"

Em caso de sucesso, a resposta traz dois ids:

{
  "stimulus_id": "stim-uuid",
  "workflow_execution_id": "wfex-uuid"
}

O segundo é a execução de workflow que o evento iniciou; acompanhe-a como qualquer outra execução.

Passo 6. Barre as entregas repetidas

Emissores tentam de novo. Repasse o id de entrega do provedor como X-Idempotency-Key: no GitHub é X-GitHub-Delivery, e no seu próprio emissor "Any stable per-event UUID" (qualquer UUID estável por evento). O orquestrador remove duplicatas por origem e chave durante 24 horas, e uma repetição responde 409:

{
  "error": "idempotent_duplicate",
  "original_stimulus_id": "stim-original-uuid"
}

Passo 7. Leia o erro que você recebe

A tabela de erros da página, na ordem em que você provavelmente vai encontrá-los:

Passo 8. Use o endpoint autenticado para chamadas internas

Um serviço que já tem uma conta no Keycloak pode dispensar o segredo compartilhado e enviar para POST /v1/stimuli com um token bearer, informando source, content e uma idempotency_key no corpo. Deixe a rota de webhook para os sistemas que você não opera.

O que a documentação deixa em aberto

Próximo

O workflow que um webhook inicia é uma máquina de estados que você escreve. Nosso guia Estados e transições de um workflow do AEGIS, passo a passo monta uma. O AEGIS se instala com o comando mostrado em 100monkeys.ai:

curl -fsSL https://get.100monkeys.ai | bash

Instale o AEGIS pelo 100monkeys.ai