Convertmax Documentation
Parler avec nous Commencer
Webhooks

Webhooks

Envoyez des événements vers Convertmax depuis des systèmes externes : routes, auth, payloads, retries et protection anti-doublons.

Copier la page
Open in ChatGPT Ouvrir avec le contexte de la page Open in Claude Ouvrir avec le contexte de la page

Utilisez cette référence lorsqu’un système externe envoie des événements vers Convertmax via HTTP.

Route

Convertmax accepte le trafic webhook entrant sur :

  • POST /ingest/inbound/:sourceConfigId

sourceConfigId pointe vers une configuration webhook entrante enregistrée qui définit :

  • le type de source
  • les paramètres d’authentification
  • le comportement optionnel de surcharge du type d’événement

Types de source entrante pris en charge

webhook

Utilisez ce type de source pour les payloads webhook JSON authentifiés qui n’ont pas besoin d’un parseur spécifique à un fournisseur.

Patterns d’authentification pris en charge :

  • Authorization: Bearer <token>
  • vérification HMAC optionnelle x-convertmax-signature lorsqu’un secret de signature est configuré

Forme de payload typique :

{
  "inbound_event_id": "evt_123",
  "event_type": "lead.updated",
  "payload": {
    "lead_id": "lead_42",
    "status": "qualified"
  }
}

make

Utilisez ce type de source lorsqu’un scénario Make.com appelle Convertmax avec un module HTTP. Le parsing et l’authentification correspondent à webhook ; source_type est enregistré comme make pour le routage et les métadonnées d’audit.

segment

Utilisez ce type de source pour envoyer des payloads d’événements de type Segment directement vers Convertmax.

Pattern d’authentification pris en charge :

  • Authorization: Bearer <token>

Formes prises en charge :

  • événements uniques de type Segment tels que track, identify, ou page
  • payloads batch de type Segment utilisant batch: []

Forme d’événement entrant normalisée

Après authentification et parsing, Convertmax standardise le trafic entrant dans une forme d’événement interne avec des champs incluant :

  • inbound_event_id
  • source_config_id
  • source_type
  • provider_event_id
  • event_type
  • received_at
  • payload
  • headers
  • meta

Protection contre le volume

La limitation de débit est appliquée avant la mise en file d’attente.

Comportement :

  • les limites sont comptées en événements normalisés
  • les payloads batch consomment une unité par élément d’événement
  • les requêtes webhook renvoient tout de même un HTTP 200
  • la protection interne contre le volume continue de contrôler la façon dont les requêtes sont traitées en arrière-plan

Gestion des doublons

La gestion des doublons est appliquée dans le consumer de la file d’attente entrante.

Comportement :

  • Convertmax vérifie (inbound_event_id, source_config_id) avant traitement
  • si cette paire existe déjà dans le magasin d’événements traités, l’événement est ignoré
  • si le traitement réussit, Convertmax archive le résultat, écrit un reçu, puis marque l’événement comme traité

Cet ordonnancement garantit qu’un événement n’est pas marqué comme traité avant que sa trace d’audit ne soit écrite.

Accusés de réception de livraison

Les requêtes webhook entrantes renvoient désormais un HTTP 200.

Une réponse réussie signifie que :

  • la requête s’est authentifiée
  • la normalisation a réussi
  • le payload de l’événement a été accepté pour mise en file d’attente

Cela ne signifie pas nécessairement que le traitement métier aval est déjà terminé.

Docs associées