Skip to main content

Report site events

POST 
/site-events

This is how a connected site tells what happened on it — an order paid, a sign-up, an abandoned cart —, up to 100 events per call. It is what the WordPress plugin calls, and any custom platform holding a connected site's API key can call it too.

The site does not need to know which flows exist: it reports the event by name, and every active, published flow with the site event trigger listening to that name receives it (at most 20 flows per event, by priority), as do the runs waiting for it. In the flow, what comes in data is available as {{trigger.<path>}} — {{trigger.order.total}} —, alongside trigger.$event (id, name, occurred_at) and trigger.$site (id, url, name).

Names. <source>.<object>.<what happened>, lowercase, 2 to 4 segments and up to 80 characters: wc.order.paid, wp.user.registered. The sources wp, wc, wcs, form and fcrc are the plugin's catalog; your own integration's events go under custom — custom.subscription.renewed.

Contact. The contact block goes through the same sync as POST /contacts/sync, with its fields in snake_case and with triggers on: a new contact or an added tag start the usual flows. Without a valid contact no flow starts — but an invalid contact block does not refuse the event, which is recorded with the reason.

Answer. 202 means recorded and queued: no flow runs inside the request. Each event answers for itself — an invalid one comes back in rejected, with its position and the reason, without costing the rest of the batch; an id the site already reported counts in duplicates and changes nothing. Delivery is "at least once": resending is safe. Each event carries up to 64 KB between data and contact.

This route never answers 402: with the account blocked, events are accepted and recorded without running flows, so the site does not pile up retries.

Idempotency. With the Idempotency-Key header, a repeat of the same call returns the first answer, with Idempotent-Replayed: true. The same key with another body is refused with 422 idempotency_key_reused; while the first request is still running, the repeat gets 409 idempotency_in_progress.

Only a connected site's API key reports events — it comes with the events:write permission. A regular API key gets 404 site_not_found.

Request​

Responses​

Events recorded. Where each one went is in accepted, duplicates or rejected.