{"title":"Automatización con webhooks","slug":"webhook-automation","category":"guides","summary":"Dispare sistemas externos cuando cambian las memorias — sincronice, notifique, automatice.","audience":["human","llm"],"tags":["guide","webhooks","automation","integration"],"difficulty":"intermediate","updated":"2026-06-27","word_count":343,"read_minutes":2,"lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Automatización con webhooks\n\nLos webhooks le permiten disparar sistemas externos cuando ocurren eventos en\nSynapse. Esta guía cubre patrones comunes de automatización.\n\n## Patrones comunes\n\n### Patrón 1: Notificar ante memoria crítica\n\nEnvíe un mensaje de Slack cuando se almacena una memoria crítica:\n\n```python\n# Webhook handler (your server)\n@app.post(\"/webhook\")\nasync def handle(request):\n payload = await request.json()\n \n # Verify signature\n if not verify_signature(payload, request.headers):\n return 401\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n if memory.get(\"priority\") == \"critical\":\n # Send Slack notification\n await slack.post(\n f\"🚨 Critical memory stored: {memory['key']}\\n{memory['content'][:200]}\"\n )\n \n return 200\n```\n\nRegistre el webhook:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/webhooks \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://my-app.com/webhook\",\n \"events\": \"memory.store\",\n \"secret\": \"my-hmac-secret\"\n }'\n```\n\n### Patrón 2: Sincronizar con sistema externo\n\nSincronice memorias con Notion, Obsidian o cualquier KB externo:\n\n```python\n@app.post(\"/webhook\")\nasync def sync_to_notion(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n # Create Notion page\n await notion.create_page(\n title=memory[\"key\"],\n content=memory[\"content\"],\n tags=memory.get(\"tags\", [])\n )\n \n elif payload[\"event\"] == \"memory.delete\":\n # Delete from Notion\n await notion.delete_page(memory_id=payload[\"data\"][\"id\"])\n \n return 200\n```\n\n### Patrón 3: Disparar CI/CD\n\nDispare un despliegue cuando se almacena una memoria \"release\":\n\n```python\n@app.post(\"/webhook\")\nasync def trigger_deploy(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"memory.store\":\n memory = payload[\"data\"]\n if memory.get(\"key\", \"\").startswith(\"release_\"):\n # Trigger GitLab pipeline\n await gitlab.trigger_pipeline(\n project=\"synapse\",\n ref=\"main\",\n variables={\"RELEASE_MEMORY_ID\": memory[\"id\"]}\n )\n \n return 200\n```\n\n### Patrón 4: Despertar al agente ante un mensaje humano\n\nDispare una ejecución del agente LLM cuando un humano envía un mensaje de chat:\n\n```python\n@app.post(\"/webhook\")\nasync def wake_agent(request):\n payload = await request.json()\n \n if payload[\"event\"] == \"chat.message_received\":\n message = payload[\"data\"]\n # Queue agent processing job\n await job_queue.enqueue(\n \"process_message\",\n message_id=message[\"id\"],\n content=message[\"content\"]\n )\n \n return 200\n```\n\n### Patrón 5: Agregar métricas\n\nHaga seguimiento del crecimiento de memoria, actividad de chat, finalización de\ntareas:\n\n```python\n@app.post(\"/webhook\")\nasync def track_metrics(request):\n payload = await request.json()\n event = payload[\"event\"]\n \n metrics = {\n \"memory.store\": \"memories_stored_total\",\n \"memory.delete\": \"memories_deleted_total\",\n \"chat.message_received\": \"messages_received_total\",\n \"task.created\": \"tasks_created_total\",\n \"task.completed\": \"tasks_completed_total\",\n }\n \n if event in metrics:\n await prometheus.increment(metrics[event])\n \n return 200\n```\n\n## Verificación de firma\n\nVerifique siempre las firmas de webhook para prevenir suplantación:\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_signature(payload_body: bytes, headers, secret: str) -> bool:\n signature = headers.get(\"X-Synapse-Signature\", \"\")\n if not signature.startswith(\"sha256=\"):\n return False\n \n expected = hmac.new(\n secret.encode(),\n payload_body,\n hashlib.sha256\n ).hexdigest()\n \n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n## Lógica de reintento\n\nSynapse reintenta los webhooks fallidos con backoff exponencial. Su handler\ndebería:\n\n1. **Devolver 200 rápidamente** — no haga trabajo pesado de forma síncrona\n2. **Encolar trabajo** — use un sistema de jobs en segundo plano\n3. **Ser idempotente** — el mismo evento puede entregarse dos veces\n\n```python\n@app.post(\"/webhook\")\nasync def handle(request):\n payload = await request.json()\n # Queue for async processing\n await job_queue.enqueue(\"process_webhook\", payload)\n # Return immediately\n return 200\n```\n\n## Depuración de webhooks\n\n### Comprobar historial de entregas\n\nLas entregas de webhook se registran. Compruebe las entregas recientes de su\nwebhook:\n\n```bash\n# Get webhook details including recent deliveries\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n### Probar el webhook manualmente\n\n```bash\n# Trigger a test event\ncurl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\"\n```\n\n### Problemas comunes\n\n| Problema | Solución |\n|-------|-----|\n| Respuestas 4xx | Compruebe que su handler devuelve 200 |\n| Respuestas 5xx | Error del servidor — revise los logs de su app |\n| Timeout | Devuelva 200 rápido, encole trabajo asíncrono |\n| Entregas duplicadas | Haga el handler idempotente |\n| Fallo de firma | Verifique que el secreto es correcto |\n\n## Mejores prácticas\n\n> [!TIP]\n> - **Verifique siempre las firmas** — nunca omita esto\n> - **Devuelva 200 rápido** — no bloquee a Synapse\n> - **Sea idempotente** — maneje entregas duplicadas\n> - **Use eventos específicos** — `memory.store` no `*`\n> - **Monitoree fallos de entrega** — configure alertas\n\n## Próximos pasos\n\n- [API de Webhooks](/docs/api/webhooks)\n- [Cron y Scheduler](/docs/api/cron)\n- [Agente LLM persistente](/docs/guides/persistent-llm-agent)\n","content_html":"

Automatización con webhooks

\n

Los webhooks le permiten disparar sistemas externos cuando ocurren eventos en\nSynapse. Esta guía cubre patrones comunes de automatización.

\n

Patrones comunes

\n

Patrón 1: Notificar ante memoria crítica

\n

Envíe un mensaje de Slack cuando se almacena una memoria crítica:

\n
# Webhook handler (your server)\n@app.post("/webhook")\nasync def handle(request):\n    payload = await request.json()\n    \n    # Verify signature\n    if not verify_signature(payload, request.headers):\n        return 401\n    \n    if payload["event"] == "memory.store":\n        memory = payload["data"]\n        if memory.get("priority") == "critical":\n            # Send Slack notification\n            await slack.post(\n                f"🚨 Critical memory stored: {memory['key']}\\n{memory['content'][:200]}"\n            )\n    \n    return 200

Registre el webhook:

\n
curl -X POST https://synapse.schaefer.zone/webhooks \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "url": "https://my-app.com/webhook",\n    "events": "memory.store",\n    "secret": "my-hmac-secret"\n  }'

Patrón 2: Sincronizar con sistema externo

\n

Sincronice memorias con Notion, Obsidian o cualquier KB externo:

\n
@app.post("/webhook")\nasync def sync_to_notion(request):\n    payload = await request.json()\n    \n    if payload["event"] == "memory.store":\n        memory = payload["data"]\n        # Create Notion page\n        await notion.create_page(\n            title=memory["key"],\n            content=memory["content"],\n            tags=memory.get("tags", [])\n        )\n    \n    elif payload["event"] == "memory.delete":\n        # Delete from Notion\n        await notion.delete_page(memory_id=payload["data"]["id"])\n    \n    return 200

Patrón 3: Disparar CI/CD

\n

Dispare un despliegue cuando se almacena una memoria "release":

\n
@app.post("/webhook")\nasync def trigger_deploy(request):\n    payload = await request.json()\n    \n    if payload["event"] == "memory.store":\n        memory = payload["data"]\n        if memory.get("key", "").startswith("release_"):\n            # Trigger GitLab pipeline\n            await gitlab.trigger_pipeline(\n                project="synapse",\n                ref="main",\n                variables={"RELEASE_MEMORY_ID": memory["id"]}\n            )\n    \n    return 200

Patrón 4: Despertar al agente ante un mensaje humano

\n

Dispare una ejecución del agente LLM cuando un humano envía un mensaje de chat:

\n
@app.post("/webhook")\nasync def wake_agent(request):\n    payload = await request.json()\n    \n    if payload["event"] == "chat.message_received":\n        message = payload["data"]\n        # Queue agent processing job\n        await job_queue.enqueue(\n            "process_message",\n            message_id=message["id"],\n            content=message["content"]\n        )\n    \n    return 200

Patrón 5: Agregar métricas

\n

Haga seguimiento del crecimiento de memoria, actividad de chat, finalización de\ntareas:

\n
@app.post("/webhook")\nasync def track_metrics(request):\n    payload = await request.json()\n    event = payload["event"]\n    \n    metrics = {\n        "memory.store": "memories_stored_total",\n        "memory.delete": "memories_deleted_total",\n        "chat.message_received": "messages_received_total",\n        "task.created": "tasks_created_total",\n        "task.completed": "tasks_completed_total",\n    }\n    \n    if event in metrics:\n        await prometheus.increment(metrics[event])\n    \n    return 200

Verificación de firma

\n

Verifique siempre las firmas de webhook para prevenir suplantación:

\n
import hmac\nimport hashlib\n\ndef verify_signature(payload_body: bytes, headers, secret: str) -> bool:\n    signature = headers.get("X-Synapse-Signature", "")\n    if not signature.startswith("sha256="):\n        return False\n    \n    expected = hmac.new(\n        secret.encode(),\n        payload_body,\n        hashlib.sha256\n    ).hexdigest()\n    \n    return hmac.compare_digest(f"sha256={expected}", signature)

Lógica de reintento

\n

Synapse reintenta los webhooks fallidos con backoff exponencial. Su handler\ndebería:

\n
    \n
  1. Devolver 200 rápidamente — no haga trabajo pesado de forma síncrona
    2. \n
  2. Encolar trabajo — use un sistema de jobs en segundo plano
    3. \n
  3. Ser idempotente — el mismo evento puede entregarse dos veces
    4. \n
\n
@app.post("/webhook")\nasync def handle(request):\n    payload = await request.json()\n    # Queue for async processing\n    await job_queue.enqueue("process_webhook", payload)\n    # Return immediately\n    return 200

Depuración de webhooks

\n

Comprobar historial de entregas

\n

Las entregas de webhook se registran. Compruebe las entregas recientes de su\nwebhook:

\n
# Get webhook details including recent deliveries\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/webhooks/wh_001

Probar el webhook manualmente

\n
# Trigger a test event\ncurl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \\\n  -H "Authorization: Bearer YOUR_MIND_KEY"

Problemas comunes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ProblemaSolución
Respuestas 4xxCompruebe que su handler devuelve 200
Respuestas 5xxError del servidor — revise los logs de su app
TimeoutDevuelva 200 rápido, encole trabajo asíncrono
Entregas duplicadasHaga el handler idempotente
Fallo de firmaVerifique que el secreto es correcto
\n

Mejores prácticas

\n

Próximos pasos

\n\n","urls":{"html":"/docs/guides/webhook-automation","text":"/docs/guides/webhook-automation?format=text","json":"/docs/guides/webhook-automation?format=json","llm":"/docs/guides/webhook-automation?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}