Documentation Index
Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
Use this file to discover all available pages before exploring further.
Goal
Architecturer un endpoint webhook capable d’absorber des pics de plusieurs centaines/milliers de webhooks par minute sans en perdre un seul, avec ack < 1 s et traitement métier asynchrone résilient.Scénario
Vous êtes un client à fort volume — chasseur national, marketplace, agrégateur — et vous recevez en continu des webhooksadvert ou property de Fluximmo, parfois en pic (rebond après une coupure, seed initial, période de marché chargée). Votre handler actuel fait du sync (DB write, fetch externe, scoring ML) : il timeout, Fluximmo retry, vous dropez du signal. Ce playbook donne l’architecture standard pour résoudre ça une bonne fois pour toutes.
Étapes
Comprendre le problème
Quand votre handler webhook fait du traitement synchrone lourd (insertion DB + fetch d’une API tierce + inférence ML), il dépasse facilement 5–10 s sur les pics. Côté Fluximmo :
- Politique de retry : 2 retries immédiats puis 10 retries espacés de 5 minutes (~50 min de fenêtre totale).
- Codes acceptés :
200,201,202,203,204,205. Tout le reste = échec → retry. - Si après les 12 tentatives votre endpoint n’a toujours pas répondu 2xx, le webhook est droppé. Pas de re-livraison ultérieure.
Architecture recommandée
Le pattern standard est : endpoint léger qui ack en < 1 s + queue + worker async.L’endpoint ne fait que trois choses : valider le header de sécurité, pousser le raw payload dans la queue, répondre 200. Tout le métier vit dans le worker.
Choisir la queue
| Queue | Quand l’utiliser | Effort d’intégration |
|---|---|---|
| AWS SQS | Déjà sur AWS, simple, scalable, managed | Faible |
| RabbitMQ | On-prem ou multi-cloud, routing avancé | Moyen |
| Redis Streams | Déjà du Redis, volume modéré | Faible |
| Google Pub/Sub | Déjà sur GCP | Faible |
| Kafka | Très haut volume + besoin de replay long | Élevé |
Worker async
Le worker consomme la queue et exécute la logique métier. Il peut être déployé en N instances pour scaler horizontalement.
Idempotence
Les retries Fluximmo (et les retries internes de votre queue) peuvent livrer le même webhook 2 fois. Sans idempotence, vous dupliquez.Patterns :
- UPSERT par
flxIdcôté DB (INSERT ... ON CONFLICT (flx_id) DO UPDATE). - Dedup key : sur chaque advert iteré, hash de
(flxId, branch, alert_id)dans une table de dédoublonnage avec TTL court (24h).
DLQ + monitoring
Dead Letter Queue (DLQ) : configurez SQS / RabbitMQ pour qu’après N échecs (typiquement 5), le message bascule dans une DLQ. C’est votre filet de sécurité — vous pouvez l’inspecter et rejouer manuellement.Métriques à monitorer :
webhooks_received(compteur) — débit entrantwebhooks_acked_under_1s(ratio) — santé de l’endpointqueue_depth(gauge) — bouchon en formation ?worker_lag_seconds(gauge) — délai bout-en-boutdlq_count(gauge) — messages échoués définitivement
- queue_depth > seuil pendant > 5 min → scale up workers
- dlq_count > 0 → investigation manuelle
- webhooks_acked_under_1s < 99 % → investiguer l’endpoint
Sécurité — header x-webhook-key
Fluximmo envoie un header Voir Concept — Webhooks pour la configuration côté dashboard et les bonnes pratiques de rotation.
x-webhook-key avec une valeur secrète que vous avez configurée. Toujours le valider avant de pousser dans la queue, sinon n’importe qui peut spammer votre endpoint.Architecture / flow
Pièges fréquents
Pour aller plus loin
- Concept — Webhooks (politique de retry, codes acceptés, header
x-webhook-key) - Concept — Match types et cycle d’alerte
- Playbook — Répliquer une BDD adverts via webhooks
- Playbook — Tracker les changements de prix
Clé test gratuite — 1 semaine
Créez un compte sur my.fluximmo.io pour récupérer une clé API test gratuite (1 semaine, accès limité). Aucun paiement, aucun appel commercial.

