Webhooks de conclusão

Em vez de consultar em loop, deixe a Leme chamar você. Passe um callbackUrl ao criar um run e a Leme envia um POST assinado para essa URL quando o run chega a um estado final — ou pausa para aprovação.

{
  "input": { "message": "Qualifique este lead." },
  "callbackUrl": "https://example.com/hooks/leme"
}

A URL precisa ser HTTPS pública na porta padrão. URLs apontando para redes privadas são rejeitadas com 422 callback_url_invalid.

Eventos

Evento	Enviado quando
`run.completed`	O run terminou com sucesso
`run.failed`	O run falhou
`run.canceled`	O run foi cancelado
`run.waiting_approval`	O run pausou aguardando aprovação humana

O payload é propositalmente enxuto — identificadores e status, nunca a resposta do agent:

{
  "type": "run.completed",
  "timestamp": "2026-07-07T18:00:00Z",
  "data": {
    "runId": "run_id",
    "agentId": "agent_id",
    "sessionId": "session_id",
    "status": "completed",
    "origin": "api",
    "metadata": { "leadId": "4821" }
  }
}

Ao recebê-lo, busque o resultado com GET /api/v1/runs/:id. Isso mantém conteúdo sensível fora do seu endpoint de webhook e garante que você sempre leia o estado mais recente.

Verificar a assinatura

Toda entrega é assinada seguindo a especificação Standard Webhooks, o mesmo esquema usado por OpenAI e Svix. Três headers acompanham a requisição:

Header	Conteúdo
`webhook-id`	ID único da entrega, estável entre retentativas
`webhook-timestamp`	Timestamp Unix (segundos) do envio
`webhook-signature`	Uma ou mais assinaturas `v1,<base64>`, separadas por espaço

Primeiro, obtenha o secret de assinatura do projeto (exige token read_write):

curl https://app.leme.ai/api/v1/project/webhook-signing-secret \
  -H "Authorization: Bearer leme_pat_v1_..."

Depois, verifique com qualquer biblioteca Standard Webhooks:

import { Webhook } from "standardwebhooks"

const webhook = new Webhook(secret) // "whsec_..."

// Lança erro se a assinatura for inválida ou antiga demais
webhook.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
})

from standardwebhooks import Webhook

webhook = Webhook(secret)  # "whsec_..."

# Lança erro se a assinatura for inválida ou antiga demais
webhook.verify(raw_body, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
})

Verifique sempre contra o corpo bruto da requisição, antes de qualquer parse de JSON. Rejeite entregas cuja assinatura não bater.

Rotacionar o secret

Se o secret vazar — ou no seu ciclo normal de rotação — gere um novo:

curl -X POST https://app.leme.ai/api/v1/project/webhook-signing-secret \
  -H "Authorization: Bearer leme_pat_v1_..."

O secret anterior continua assinando por 24 horas, para você fazer a transição sem perder entregas. Durante essa janela, webhook-signature carrega duas assinaturas — a entrega é válida se qualquer uma bater, o que toda biblioteca Standard Webhooks já trata por você.

Retentativas e confiabilidade

Entregas são at least once. Se o seu endpoint não responder 2xx em 15 segundos, a Leme tenta de novo: após 1 minuto, 5 minutos, 30 minutos e 2 horas. Depois de cinco tentativas falhas, a entrega é marcada como esgotada. Como retentativas podem se sobrepor ao seu processamento, torne seu handler idempotente — deduplique pelo webhook-id. Você pode inspecionar o estado da entrega a qualquer momento no recurso do run:

{
  "callback": {
    "url": "https://example.com/hooks/leme",
    "lastStatus": "delivered",
    "attempts": 1
  }
}

Boas práticas

Responda rápido. Confirme com 2xx imediatamente e processe de forma assíncrona; o timeout de 15 segundos inclui o seu handler.
Deduplique pelo webhook-id. Retentativas reutilizam o mesmo ID.
Não confie só no payload. Verifique a assinatura e busque o run pela API para obter o estado autoritativo.
Fique de olho em entregas esgotadas. Se esgotaram, seu endpoint ficou fora do ar por horas — consulte os runs em andamento para se atualizar.

Primeiros passos

Agents

Ferramentas e permissões

Automação

Artefatos

Workspace

API

Webhooks de conclusão

Eventos

Verificar a assinatura

Rotacionar o secret

Retentativas e confiabilidade

Boas práticas

​Eventos

​Verificar a assinatura

​Rotacionar o secret

​Retentativas e confiabilidade

​Boas práticas

Eventos

Verificar a assinatura

Rotacionar o secret

Retentativas e confiabilidade

Boas práticas