Convertmax Documentation
Talk to us Get started
Reference

Webhook Ingest

Reference for Convertmax inbound webhook routes, supported source types, authentication, and duplicate handling.

Copy page
Open in ChatGPT Open with page context Open in Claude Open with page context

Use this reference when integrating an external system with the Convertmax inbound webhook pipeline.

Route

Convertmax accepts inbound webhook traffic on:

  • POST /ingest/inbound/:sourceConfigId

sourceConfigId points to a saved inbound webhook setup that defines:

  • the source type
  • authentication settings
  • optional event-type override behavior

Supported inbound source types

webhook

Use this source type for authenticated JSON webhook payloads that do not need a special provider-specific parser.

Supported auth patterns:

  • Authorization: Bearer <token>
  • optional x-convertmax-signature HMAC verification when a signing secret is configured

Typical payload shape:

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

segment

Use this source type when sending Segment-style event payloads directly into Convertmax.

Supported auth pattern:

  • Authorization: Bearer <token>

Supported shapes:

  • single Segment-style events such as track, identify, or page
  • Segment-style batch payloads using batch: []

Normalized inbound event shape

After authentication and parsing, Convertmax standardizes inbound traffic into an internal event shape with fields including:

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

Volume protection

Rate limiting is enforced before queueing.

Behavior:

  • limits are counted in normalized events
  • batch payloads consume one unit per event item
  • webhook requests still return HTTP 200
  • internal volume protection still controls how requests are handled behind the scenes

Duplicate handling

Duplicate handling is enforced in the inbound queue consumer.

Behavior:

  • Convertmax checks (inbound_event_id, source_config_id) before processing
  • if that pair already exists in the processed-event store, the event is skipped
  • if processing succeeds, Convertmax archives the result, writes a receipt, and then marks the event as processed

This ordering ensures an event is not marked processed before its audit trail is written.

Delivery acknowledgements

Inbound webhook requests now return HTTP 200.

A successful response means:

  • the request authenticated
  • normalization succeeded
  • the event payload was accepted for enqueueing

It does not necessarily mean downstream business processing has already completed.