Openhook

npx add-mcp 'https://openhook.dev/mcp'

Openhook

Uma caixa de entrada de eventos para agentes de IA. Crie uma URL pública, aguarde um callback, inspecione o que chegou e continue a tarefa.

O Openhook opera seus próprios servidores de captura HTTP, SMTP e DNS autoritativo. Os eventos ficam em seu banco de dados SQLite. Nenhum serviço de webhook externo está envolvido.

Experimente ou hospede

Crie uma caixa de entrada gratuita sem conta, ou conecte seu agente. O Pro hospedado opcional fornece caixas de entrada persistentes e recuperação de conta; veja a disponibilidade e planos atuais. A auto-hospedagem permanece licenciada sob MIT, sem necessidade de conta ou assinatura do Openhook.

Receitas práticas: encaminhamento local, callbacks de push do GitHub e callbacks de teste do Stripe.

Primeiro callback em menos de um minuto

Com o Python 3 instalado, clone o repositório e execute o exemplo descartável:

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

Ele cria uma caixa de entrada gratuita em openhook.dev, envia um callback real, verifica os bytes originais e, em seguida, exclui sua caixa de entrada e payload. O token privado permanece na memória. Nenhuma conta, chave de API ou dependências Python são necessárias para este exemplo. Metadados mínimos de atividade operacional permanecem após a exclusão.

Instale a habilidade do agente

Para Codex, Claude Code e outros clientes compatíveis com Agent Skills:

npx skills add openhook-dev/openhook-inbox --skill openhook

A configuração e permissões da habilidade explicam a conexão MCP, fallback REST, encaminhamento local e tratamento de tokens privados de caixa de entrada. Instalar a habilidade não instala nem inicia o servidor.

Execute

A partir do checkout, instale uv e inicie seu próprio servidor:

uv sync
uv run openhook --http

Abra http://127.0.0.1:8788/app.. O site, a API de captura e o endpoint MCP Streamable HTTP compartilham um único serviço e um único armazenamento durável.

Conecte um cliente MCP a http://127.0.0.1:8788/mcp, ou use uv run openhook para stdio. Um processo stdio local compartilha o mesmo banco de dados com um processo HTTP em execução quando ambos usam o mesmo OPENHOOK_DATABASE. O processo HTTP deve estar em execução para receber callbacks HTTP. Verifique o mesmo loop contra seu servidor com python3 examples/first_callback.py --url http://127.0.0.1:8788. Provedores externos precisam de uma origem publicamente acessível; o exemplo localhost apenas prova que seu servidor local funciona.

Lançamentos do GitHub fornecem código-fonte versionado e distribuições Python quando disponíveis. O pacote openhook-mcp não está atualmente publicado no PyPI; use o checkout do código-fonte ou um artefato de lançamento em vez de assumir que uma instalação via índice de pacotes funciona.

Fluxo de trabalho do agente

1. Chame create_webhook. Salve o token de gerenciamento privado ohk_.
2. Forneça a URL HTTP pública, endereço de e-mail ou nome DNS retornado ao remetente.
3. Chame wait_for_request com o token de gerenciamento.
4. Inspecione o evento e aja. Reconecte usando o cursor next_since retornado.

Endereços de captura públicos não podem ler ou excluir eventos. Gire um token de gerenciamento comprometido com rotate_webhook_token. A rotação preserva os endereços públicos.

Caixas de entrada anônimas expiram em até sete dias. Cada uma aceita até 1000 eventos retidos. Quando cheia, a captura retorna um erro de capacidade em vez de remover eventos aceitos. Eventos individuais são limitados a 1 MB. Endereços de e-mail e DNS são retornados apenas quando seus listeners estão configurados.

Ferramentas nativas

29 ferramentas cobrem criação de caixa de entrada, configuração de resposta, rotação de token, inspeção de eventos, pesquisa literal, notas, exportação JSON/CSV, download de bytes exatos, esperas HTTP/e-mail, eventos de teste, extração de links/códigos, verificação de callbacks, respostas atrasadas, assinaturas de provedores, exclusão e histórico de atividades. Veja a referência de ferramentas gerada.

Histórico de atividades durável

Cada recebimento HTTP, e-mail e DNS aceito e cada mutação local bem-sucedida grava um registro de atividade na mesma transação que sua mudança de estado. Entregas duplicadas da fonte também recebem registros. O histórico inclui notas, configurações de resposta, respostas atrasadas, rotação de token, assinaturas, exclusão e expiração. Leia com get_webhook_activity ou POST /api/call com action: activity, o token privado, um cursor since e um limit limitado.

Metadados mínimos de atividade permanecem após a exclusão e expiração do payload. Eles excluem tokens privados, credenciais de provedores, corpos, notas e segredos de assinatura. Eventos existentes são marcados como importados; seu histórico de mutação anterior não pode ser reconstruído. O aplicativo anexa registros; isso não é um log criptograficamente à prova de adulteração. Capturas rejeitadas não são armazenadas como eventos aceitos.

Defina verification_secret até configure_webhook para exigir HMAC SHA256 em corpos HTTP brutos. O Openhook aceita X-Openhook-Signature: sha256=… e o X-Hub-Signature-256 do GitHub. Assinaturas inválidas são rejeitadas antes da captura. Idempotency-Key e X-GitHub-Delivery deduplicam tentativas dentro de uma caixa de entrada.

URLs de entrada com ?openhook_wait=1 aguardam até 20 segundos por uma resposta do agente. Inicie respond_to_next_request antes de enviar tal solicitação.

Configuração

Variável de ambiente	Propósito
OPENHOOK_ORIGIN	Origem pública, padrão http://127.0.0.1:8788
OPENHOOK_DATABASE	Caminho do SQLite, padrão data/openhook.sqlite3
OPENHOOK_EMAIL_DOMAIN	Domínio de e-mail de entrada próprio; não definido desativa SMTP
OPENHOOK_SMTP_PORT	Listener SMTP, padrão 2525; mapeie a porta pública 25
OPENHOOK_DNS_DOMAIN	Zona de callback delegada própria; não definido desativa DNS
OPENHOOK_DNS_PORT	Listener DNS UDP/TCP, padrão 5353; mapeie a porta pública 53
OPENHOOK_DNS_ADDRESS	Endereço IPv4 retornado para consultas DNS A

O SMTP rejeita e-mails para caixas de entrada desconhecidas e nunca retransmite e-mails. O DNS responde apenas para a zona configurada e não fornece recursão.

Implantação

Use o Dockerfile e compose.dokploy.yaml em um projeto Dokploy separado. Anexe o domínio do Openhook ao serviço openhook, porta 8788. Seu volume de dados nomeado sobrevive a lançamentos. Veja notas de implantação.

Registro de provedores e entrega local

Chame register_github_webhook, register_stripe_webhook ou register_linear_webhook para criar uma caixa de entrada nativa e assinar na fonte. As credenciais da API do provedor são usadas transitoriamente e nunca salvas. Assinaturas brutas são verificadas antes da captura; carimbos de data/hora do Stripe e Linear são verificados para replay. Chame unregister_webhook antes que a caixa de entrada expire para remover a assinatura da fonte.

Para entrega local, defina OPENHOOK_TOKEN para seu token de caixa de entrada privado e execute:

uv run openhook-listen --forward http://127.0.0.1:8080/webhook
# Or wake an already configured local OpenClaw:
uv run openhook-listen --openclaw

A entrega do OpenClaw também requer OPENCLAW_HOOKS_TOKEN. Sem destino, o listener imprime eventos como JSON. Ele se conecta externamente via HTTPS, salva um cursor após entrega bem-sucedida e tenta novamente entregas com falha. A entrega é pelo menos uma vez: os destinatários devem deduplicar por ID de evento. Cada destino tem seu próprio cursor; execute um listener por destino e token. O provisionamento de túnel SSH gerenciado não está incluído.

Verificação

O site usa uma interface de texto centralizada e a fonte variável Paper Mono v1.000 auto-hospedada e o logotipo aprovado do Openhook. Páginas públicas e esquemas de ferramentas ao vivo são renderizados em HTML antes da execução do JavaScript. Os pontos de entrada do agente incluem /agents.md, /skill.md, /llms.txt, /llms-full.txt, /docs.md e /openapi.json. Sua demonstração de webhook cria uma caixa de entrada, envia um callback real e lê o evento capturado. Atualize as versões de ativos após editar web/:

bun run build

uv run --extra dev pytest
node --check web/assets/app.js

Os testes exercitam captura HTTP nativa, isolamento de token privado, verificações de assinatura, idempotência, persistência, expiração, MCP e SMTP local real e DNS UDP/TCP.

Licenciado sob MIT. Avisos de terceiros necessários estão em THIRD_PARTY_NOTICES.md.

Desenvolvimento hospedado e contribuição

Contas e cobrança estão desabilitadas por padrão. A edição hospedada opcional adiciona identidade GitHub, chaves de agente revogáveis, caixas de entrada próprias e direitos verificados de fatura paga. Veja operações hospedadas para configuração, limites, requisitos de modo de teste e dependências de lançamento. Nenhum comerciante real ou lançamento pago está implícito pela presença deste código.

Veja contribuição e relato de segurança.