API Webhooks

Les webhooks permettent de recevoir des rappels HTTP lorsque des événements se produisent dans Synapse. Parfait pour déclencher des automatisations externes, envoyer des notifications ou synchroniser vers d'autres systèmes.

Endpoints

POST /webhooks

Enregistre un nouveau webhook.

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

Réponse :

{
  "id": "wh_001",
  "url": "https://my-app.com/webhook",
  "events": ["memory.*"],
  "enabled": true,
  "created_at": "2026-06-27T..."
}

GET /webhooks

Liste tous les webhooks du mind courant.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks

GET /webhooks/:id

Récupère un seul webhook.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

PUT /webhooks/:id

Met à jour un webhook (URL, événements, secret ou drapeau enabled).

curl -X PUT https://synapse.schaefer.zone/webhooks/wh_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

DELETE /webhooks/:id

Supprime un webhook.

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001

Types d'événements

Payload du webhook

Lorsqu'un événement se déclenche, Synapse envoie un POST vers votre URL :

{
  "event": "memory.store",
  "timestamp": "2026-06-27T...",
  "mind_id": "m_xyz789",
  "data": {
    "id": "mem_001",
    "category": "fact",
    "key": "user_name",
    "content": "Michael Schäfer"
  }
}

Vérification de signature

Si vous définissez un secret, Synapse signe chaque payload avec HMAC-SHA256 :

X-Synapse-Signature: sha256=<hex-hmac>

Vérifiez dans votre gestionnaire :

import hmac, hashlib

def verify_signature(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Schéma : synchronisation en temps réel

# Votre gestionnaire de webhook
@app.post("/webhook")
async def handle_webhook(request):
    body = await request.body()
    signature = request.headers.get("X-Synapse-Signature", "")
    if not verify_signature(body, signature, WEBHOOK_SECRET):
        return 401

    event = json.loads(body)
    if event["event"] == "memory.store":
        # Synchroniser vers un autre système
        sync_to_external(event["data"])
    elif event["event"] == "chat.message_received":
        # Déclencher le réveil de l'agent
        notify_agent(event["data"])

Prochaines étapes

• Cron & Scheduler
• Guide d'automatisation par webhooks