The ingest API

The ingest API is the single entry point for events coming into 2mee. Sending an event can start or advance a flow. It is the same endpoint whether you POST directly, use a generic webhook, or connect a provider like Segment.

This is the canonical ingest contract

The payload below is the public ingest contract, owned in the 2mee platform and published here as the canonical schema. It is versioned and changes are additive only within a version — new optional fields may appear; existing fields and meanings don’t change. Build against the version string.

Endpoint

POST https://hooks.2mee.com/v1/in/{inboundKey}
Content-Type: application/json
webhook-id: msg_01H...           # stable message id (idempotency key)
webhook-timestamp: 1718703600    # unix seconds, for replay rejection
webhook-signature: v1,<base64>   # HMAC-SHA256 over the raw body — see signing

• {inboundKey} identifies your connection (and therefore your account).
• The body is signed with that connection’s secret. See inbound signing & verification.

Request envelope

{
  "version": "1",
  "messageId": "msg_01HZX9...",
  "occurredAt": "2026-06-18T10:00:00Z",
  "eventType": "purchase_completed",
  "clientUserId": "user_8842",
  "attributes": {
    "email": "sam@example.com",
    "plan": "pro",
    "basketValue": 149.0
  },
  "endpoints": {
    "email": "sam@example.com",
    "phone": "+447700900000"
  },
  "raw": { }
}

Field	Type	Required	Notes
version	string	yes	Ingest contract version. Currently "1".
messageId	string	yes	Stable across retries — used as the idempotency key.
occurredAt	string (ISO-8601)	yes	When the event happened, UTC.
eventType	string	yes	Your event name. Trigger routing matches on this.
clientUserId	string	no	Your id for the person. Links the event to a visitor/participant; held if not yet linked.
attributes	object	no	Key/value data mapped onto the visitor and tested by conditions.
endpoints	object	no	email / phone for reaching the person (used by campaigns).
raw	object	no	Your original payload, retained for audit.

Responses

Status	Meaning
202 Accepted	Received, signature valid, queued for the engine.
401 Unauthorized	Signature missing or wrong.
404 Not Found	Unknown inboundKey.
409 Conflict	Duplicate messageId (already processed) — safe to treat as success.
413 Payload Too Large	Body exceeds the size cap (256 KB).
429 Too Many Requests	Rate limited — honour Retry-After.

See the error model and rate limits.

Idempotency & replay

• Send a stable messageId that doesn’t change across retries. 2mee dedupes on it, so re-delivering the same message can’t restart someone’s flow.
• Include webhook-timestamp. Events outside a 5-minute window (with small clock-skew tolerance) are rejected as replays.

See retries & idempotency.

Provider payloads

When you connect a named provider, you don’t build this envelope yourself — the provider’s native payload (e.g. a Segment track) is normalised into it on the way in. See Connect Segment.