Hermes

Hermes actúa como puente entre tus aplicaciones y terceros. Gestiona la autenticación OAuth, reenvía peticiones REST y GraphQL, y enruta webhooks entrantes hacia las apps suscritas.

¿Para qué sirve?

• Proxy autenticado hacia Zoho CRM, Books y WorkDrive
• Relay GraphQL hacia Kraken sin queries embebidas
• Recepción y reenvío de webhooks de Zoho con firma HMAC
• Centralización de tokens OAuth y reintentos HTTP

URL base de producción:https://hermes.oees.tech/api/v1

Para despliegue, variables de entorno y operaciones, consulta el repositorio: https://github.com/oees/hermes

Llamadas salientes

Your App ──(X-API-Key)──▶ Hermes ──(OAuth / JWT)──▶ Third party
                              │
                              ▼
                    ┌──────────────────────┐
                    │  PostgreSQL (DO)     │
                    └──────────────────────┘

Webhooks entrantes

Zoho ──webhook──▶ Hermes ──route by subscription_name──▶ Your App(s)
                              │
                              ▼
                         Celery worker
                              │
                              ▼
                    POST + HMAC signature

Componentes principales

• FastAPI API — Endpoints HTTP, CORS, validación de API keys
• Celery worker — Entrega asíncrona de webhooks con reintentos
• PostgreSQL — Credenciales OAuth, clientes API, suscripciones
• Integrations — Clientes REST/GraphQL en app/integrations/

API key (caller → Hermes)

Incluye el header en cada petición a endpoints protegidos:

X-API-Key: hms_live_{32_hex}

Generar una API key

python -m app.cli.commands create-api-key my-app

Errores

Una API key inválida o ausente devuelve HTTP 401 — Invalid or missing API key.

Hermes → terceros

• Zoho CRM, Books, WorkDrive: OAuth2 refresh token → access token
• Kraken: client credentials → JWT via auth server

Zoho CRM

Proxy REST hacia la API v8 y consultas COQL de solo lectura.

• POST /zoho/setup — almacenar tokens OAuth
• POST /zoho/proxy — proxy REST (GET/POST/PUT/PATCH/DELETE)
• POST /zoho/query — consultas COQL

Zoho Books

Proxy REST contable; Hermes inyecta organization_id automáticamente.

• POST /zoho-books/setup — bootstrap con refresh_token
• POST /zoho-books/proxy — proxy REST Books v3

Zoho WorkDrive

Proxy REST, descargas y subida de archivos (máx. 250 MB).

• POST /zoho-workdrive/setup — bootstrap con refresh_token
• POST /zoho-workdrive/proxy — proxy REST WorkDrive
• POST /zoho-workdrive/upload — subida multipart

Kraken

Relay GraphQL puro: el caller envía query, variables y operationName.

• POST /kraken/graphql — relay sin queries embebidas

Flujo

1. Zoho envía POST /api/v1/webhooks/zoho con subscription_name en el body
2. Hermes busca suscripciones activas cuyo name coincida
3. Celery encola la entrega a cada target_url
4. Tu app verifica X-Hermes-Signature con el secret de la suscripción

Enrutado por subscription_name

Zoho puede enviar un nombre o varios. Formatos soportados:

• String simple: "my-app"
• String entre corchetes: "[app-a, app-b]"
• Array JSON: ["app-a", "app-b"]

Crear suscripción

El campo name es la clave de enrutado. module y events son solo metadata; Hermes no filtra webhooks entrantes por ellos.

Payload que recibe tu app

• integration, module, event, data, timestamp, subscription_id
• Headers: X-Hermes-Signature, X-Hermes-Subscription-Id

Verificar firma

Compara el HMAC-SHA256 del body JSON con el header:

X-Hermes-Signature: sha256={hex}

Reintentos

Hasta 5 reintentos con backoff exponencial (10s, 20s, 40s, 80s, 160s).

Health check

curl https://hermes.oees.tech/api/v1/health

Proxy Zoho CRM

curl -X POST https://hermes.oees.tech/api/v1/zoho/proxy \
  -H "X-API-Key: hms_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "endpoint": "/Leads/12345"
  }'

Crear suscripción webhook

curl -X POST https://hermes.oees.tech/api/v1/webhooks/webhook-subscriptions \
  -H "X-API-Key: hms_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "integration": "zoho",
    "module": "Leads",
    "events": ["create", "edit"],
    "target_url": "https://my-app.com/webhooks"
  }'