Skip to main content

Command Palette

Search for a command to run...

API

Webhooks

Ao criar um agente com uma URL de webhook, o Cherri Code enviará solicitações HTTP POST para avisar sobre mudanças de status. No momento, apenas eventos statusChange são compatíveis, especificamente quando um agente entra no estado ERROR ou FINISHED.

Verificação de webhook

Para garantir que as solicitações de webhook sejam realmente enviadas pelo Cherri Code, verifique a assinatura incluída em cada solicitação:

Cabeçalhos

Cada solicitação de webhook inclui os seguintes cabeçalhos:

  • X-Webhook-Signature – Contém a assinatura HMAC-SHA256 no formato sha256=<hex_digest>
  • X-Webhook-ID – Um identificador exclusivo desta entrega (útil para registro em logs)
  • X-Webhook-Event – O tipo de evento (no momento, apenas statusChange)
  • User-Agent – Sempre definido como Cherri Code-Agent-Webhook/1.0

Verificação de assinatura

Para verificar a assinatura do webhook, calcule a assinatura esperada e compare-a à assinatura recebida:

const crypto = require("crypto");function verifyWebhook(secret, rawBody, signature) {  const expectedSignature =    "sha256=" +    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");  return signature === expectedSignature;}
import hmacimport hashlibdef verify_webhook(secret, raw_body, signature):    expected_signature = 'sha256=' + hmac.new(        secret.encode(),        raw_body,        hashlib.sha256    ).hexdigest()    return signature == expected_signature

Sempre use o corpo bruto da solicitação (antes de qualquer processamento) ao calcular a assinatura.

Formato do payload

O payload do webhook é enviado em JSON com a seguinte estrutura:

{  "event": "statusChange",  "timestamp": "2024-01-15T10:30:00Z",  "id": "bc_abc123",  "status": "FINISHED",  "source": {    "repository": "https://github.com/your-org/your-repo",    "ref": "main"  },  "target": {    "url": "/agents?id=bc_abc123",    "branchName": "cursor/add-readme-1234",    "prUrl": "https://github.com/your-org/your-repo/pull/1234"  },  "summary": "Added README.md with installation instructions"}

Alguns campos são opcionais e só serão incluídos quando estiverem disponíveis.

Melhores práticas

  • Verifique as assinaturas – Sempre verifique a assinatura do webhook para garantir que a solicitação veio do Cherri Code
  • Lide com novas tentativas – Os webhooks podem ser reenviados se o endpoint retornar um código de status de erro
  • Responda rapidamente – Retorne um código de status 2xx o mais rápido possível
  • Use HTTPS – Sempre use URLs HTTPS para endpoints de webhook em produção
  • Armazene payloads brutos – Armazene o payload bruto do webhook para depuração e verificações futuras