# 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.

```bash
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 :

```json
{
  "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.

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

### GET /webhooks/:id

Récupère un seul webhook.

```bash
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).

```bash
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.

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

## Types d'événements

| Schéma | Se déclenche quand |
|---------|------------|
| `memory.*` | Tout événement de mémoire |
| `memory.store` | Nouvelle mémoire stockée |
| `memory.update` | Mémoire mise à jour |
| `memory.delete` | Mémoire supprimée |
| `chat.*` | Tout événement de chat |
| `chat.message_received` | Nouveau message de l'humain |
| `task.*` | Tout événement de tâche |
| `task.created` | Nouvelle tâche créée |
| `task.completed` | Tâche marquée comme terminée |
| `*` | Tous les événements |

## Payload du webhook

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

```json
{
  "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 :

```python
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

```python
# 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](/docs/api/cron)
- [Guide d'automatisation par webhooks](/docs/guides/webhook-automation)