{"title":"API Webhooks","slug":"webhooks","category":"api","summary":"Enregistrez des rappels HTTP pour les événements de mémoire, chat et tâches — soyez notifié quand les données changent.","audience":["human","llm"],"tags":["api","webhooks","automation","events"],"difficulty":"intermediate","updated":"2026-06-27","word_count":220,"read_minutes":1,"llm_context":"Auth: Mind Key\nRegister: POST /webhooks { url, events, secret? }\nList: GET /webhooks\nGet: GET /webhooks/:id\nUpdate: PUT /webhooks/:id { url?, events?, secret?, enabled? }\nDelete: DELETE /webhooks/:id\nEvents: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed\nSecret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header\nPattern: register webhook → receive POST → process event → call Synapse API\n","lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# API Webhooks\n\nLes webhooks permettent de recevoir des rappels HTTP lorsque des événements se\nproduisent dans Synapse. Parfait pour déclencher des automatisations externes, envoyer\ndes notifications ou synchroniser vers d'autres systèmes.\n\n## Endpoints\n\n### POST /webhooks\n\nEnregistre un nouveau 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.*\",\n \"secret\": \"my-hmac-secret-min-8-chars\"\n }'\n```\n\nRéponse :\n\n```json\n{\n \"id\": \"wh_001\",\n \"url\": \"https://my-app.com/webhook\",\n \"events\": [\"memory.*\"],\n \"enabled\": true,\n \"created_at\": \"2026-06-27T...\"\n}\n```\n\n### GET /webhooks\n\nListe tous les webhooks du mind courant.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks\n```\n\n### GET /webhooks/:id\n\nRécupère un seul webhook.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n### PUT /webhooks/:id\n\nMet à jour un webhook (URL, événements, secret ou drapeau enabled).\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/webhooks/wh_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"enabled\": false}'\n```\n\n### DELETE /webhooks/:id\n\nSupprime un webhook.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/webhooks/wh_001\n```\n\n## Types d'événements\n\n| Schéma | Se déclenche quand |\n|---------|------------|\n| `memory.*` | Tout événement de mémoire |\n| `memory.store` | Nouvelle mémoire stockée |\n| `memory.update` | Mémoire mise à jour |\n| `memory.delete` | Mémoire supprimée |\n| `chat.*` | Tout événement de chat |\n| `chat.message_received` | Nouveau message de l'humain |\n| `task.*` | Tout événement de tâche |\n| `task.created` | Nouvelle tâche créée |\n| `task.completed` | Tâche marquée comme terminée |\n| `*` | Tous les événements |\n\n## Payload du webhook\n\nLorsqu'un événement se déclenche, Synapse envoie un POST vers votre URL :\n\n```json\n{\n \"event\": \"memory.store\",\n \"timestamp\": \"2026-06-27T...\",\n \"mind_id\": \"m_xyz789\",\n \"data\": {\n \"id\": \"mem_001\",\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"Michael Schäfer\"\n }\n}\n```\n\n## Vérification de signature\n\nSi vous définissez un `secret`, Synapse signe chaque payload avec HMAC-SHA256 :\n\n```\nX-Synapse-Signature: sha256=\n```\n\nVérifiez dans votre gestionnaire :\n\n```python\nimport hmac, hashlib\n\ndef verify_signature(payload_body: bytes, signature: str, secret: str) -> bool:\n expected = hmac.new(\n secret.encode(),\n payload_body,\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n## Schéma : synchronisation en temps réel\n\n```python\n# Votre gestionnaire de webhook\n@app.post(\"/webhook\")\nasync def handle_webhook(request):\n body = await request.body()\n signature = request.headers.get(\"X-Synapse-Signature\", \"\")\n if not verify_signature(body, signature, WEBHOOK_SECRET):\n return 401\n\n event = json.loads(body)\n if event[\"event\"] == \"memory.store\":\n # Synchroniser vers un autre système\n sync_to_external(event[\"data\"])\n elif event[\"event\"] == \"chat.message_received\":\n # Déclencher le réveil de l'agent\n notify_agent(event[\"data\"])\n```\n\n## Prochaines étapes\n\n- [Cron & Scheduler](/docs/api/cron)\n- [Guide d'automatisation par webhooks](/docs/guides/webhook-automation)\n","content_html":"

API Webhooks

\n

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

\n

Endpoints

\n

POST /webhooks

\n

Enregistre un nouveau 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.*",\n    "secret": "my-hmac-secret-min-8-chars"\n  }'

Réponse :

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

GET /webhooks

\n

Liste tous les webhooks du mind courant.

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

GET /webhooks/:id

\n

Récupère un seul webhook.

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

PUT /webhooks/:id

\n

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

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

DELETE /webhooks/:id

\n

Supprime un webhook.

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

Types d'événements

\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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SchémaSe déclenche quand
memory.*Tout événement de mémoire
memory.storeNouvelle mémoire stockée
memory.updateMémoire mise à jour
memory.deleteMémoire supprimée
chat.*Tout événement de chat
chat.message_receivedNouveau message de l'humain
task.*Tout événement de tâche
task.createdNouvelle tâche créée
task.completedTâche marquée comme terminée
*Tous les événements
\n

Payload du webhook

\n

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

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

Vérification de signature

\n

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

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

Vérifiez dans votre gestionnaire :

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

Schéma : synchronisation en temps réel

\n
# Votre gestionnaire de webhook\n@app.post("/webhook")\nasync def handle_webhook(request):\n    body = await request.body()\n    signature = request.headers.get("X-Synapse-Signature", "")\n    if not verify_signature(body, signature, WEBHOOK_SECRET):\n        return 401\n\n    event = json.loads(body)\n    if event["event"] == "memory.store":\n        # Synchroniser vers un autre système\n        sync_to_external(event["data"])\n    elif event["event"] == "chat.message_received":\n        # Déclencher le réveil de l'agent\n        notify_agent(event["data"])

Prochaines étapes

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