> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanifyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recevez les changements d'état des générations Fanify Hub.

Les webhooks évitent d'interroger chaque génération. Fanify Hub envoie `generation.running` au démarrage effectif de l'exécution. Il envoie `generation.completed` pour tout état final : succès, échec ou annulation.

Une génération annulée ou échouée pendant son attente en file n'émet pas `generation.running`.

## Enregistrer un endpoint

```bash theme={null}
curl https://fanifyai.com/api/v1/hub/webhooks \
  -H "Authorization: Bearer $FANIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fanify/webhook","events":["generation.running","generation.completed"]}'
```

La réponse `201` contient un `secret` une seule fois. L'URL doit utiliser HTTPS et être accessible publiquement. Un compte peut enregistrer au maximum **5 endpoints actifs**.

## Vérifier une livraison

Chaque requête contient :

```text theme={null}
X-Fanify-Event: generation.completed
X-Fanify-Delivery: 0193f2c1-8f4a-7c31-9a02-6f5b1d0e77aa
X-Fanify-Signature: sha256=<signature hexadécimale minuscule>
```

Le corps JSON utilise cette enveloppe :

```json theme={null}
{
  "id": "0193f2c1-8f4a-7c31-9a02-6f5b1d0e77aa",
  "event": "generation.completed",
  "created_at": "2026-09-07T10:00:31Z",
  "data": {
    "id": "0192f3a4-8c1e-7b2a-9f10-2b6d4e0c9a11",
    "model": "nano-banana-2",
    "is_llm": false,
    "status": "succeeded",
    "input": { "prompt": "a cat", "resolution": "2K" },
    "estimated_cost": 0.040000,
    "billed_cost": 0.040000,
    "currency": "EUR",
    "outputs": [
      {
        "index": 0,
        "media_type": "image/png",
        "url": "https://fanifyai.com/api/v1/hub/files/8Jd2kQ7pR1sT4uV6wX9yZ0aB2cD4eF6gH8iJ0kL2mN4",
        "size": 812345,
        "expires_at": "2026-09-14T10:00:31Z"
      }
    ],
    "error": null,
    "missing": [],
    "created_at": "2026-09-07T10:00:00Z",
    "started_at": "2026-09-07T10:00:01Z",
    "completed_at": "2026-09-07T10:00:31Z"
  }
}
```

`data` contient l'[objet génération](/fr/hub/generations) complet. La propriété `id` de l'enveloppe est identique au header `X-Fanify-Delivery`.

Calculez `HMAC-SHA256(secret, corps brut)` et comparez le résultat en temps constant avec `X-Fanify-Signature`.

<Warning>
  Vérifiez la signature sur les octets bruts avant de parser le JSON. Une re-sérialisation change la signature.
</Warning>

Une livraison réussie peut être répétée et l'ordre n'est pas garanti. Dédupliquez les requêtes avec `X-Fanify-Delivery`.

Fanify Hub réessaie après une réponse `429`, une réponse `5xx`, un timeout ou un échec de connexion. Les autres réponses `4xx` abandonnent immédiatement la livraison. Une livraison réessayée effectue au maximum **8 tentatives**, avec des délais de 30 secondes, 2 minutes, 10 minutes, 1 heure, 6 heures, 24 heures puis 72 heures. Le dernier échec est exposé dans `last_error` par `GET /api/v1/hub/webhooks`.

`GET /api/v1/hub/webhooks` liste les endpoints sans leur secret. `DELETE /api/v1/hub/webhooks/{id}` révoque un endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.