Events: Real-Time Notifications in Synq

Synq emits a structured event every time something meaningful changes on the platform — a new order arrives, a product is updated, inventory shifts. Each event is the authoritative record of what happened, when it happened, and which user and organization triggered it. Your integrations, automations, and downstream systems can subscribe to these events via webhooks and react in real time, giving you a fully auditable and up-to-date picture of your commerce operations.

Why events matter

Traditional polling-based integrations check for changes on a schedule, which means you are always slightly behind. With Synq’s event-driven model, your systems receive a notification the moment something changes — no polling, no delay, no missed updates. Because every event carries a unique ID, a precise timestamp, and the full identity context of who triggered the action, you get end-to-end traceability across every operation without any extra instrumentation.

Reliable delivery

If your endpoint is temporarily unavailable, Synq retries delivery automatically so you never miss a change.

Fully auditable

Every event records the exact user, organization, and tenant responsible for the action, giving you a complete audit trail.

Consistent structure

All events share the same envelope format regardless of type, so your consumer code stays simple and predictable.

Tenant-isolated

Your webhook endpoint only ever receives events that originated within your own Tenant — never events from other organizations on the platform.

Common event types

Event type	Triggered when
`order.created`	A new order is placed or imported into Synq
`order.updated`	An existing order’s status, line items, or details change
`product.created`	A new product is added to your catalog
`product.updated`	A product’s price, description, or attributes are modified
`inventory.adjusted`	Stock levels change due to a sale, return, or manual adjustment
`integration.synced`	A connected sales channel or ERP completes a synchronization cycle

Subscribe only to the event types your integration cares about. This keeps your handler logic focused and reduces unnecessary processing at your endpoint.

Event payload structure

Every Synq event uses the same DomainEvent envelope regardless of type. The payload field contains the data specific to the event that occurred.

{
  "event_id": "e5d3a1f0-7c82-4b69-a91e-3f204dc8b07a",
  "event_type": "order.created",
  "timestamp": "2024-12-04T15:32:07.412Z",
  "tenant_id": "a3f8c120-4e72-4b91-9d63-1c5e7a09bf44",
  "org_id": "7b91d204-fc3a-48e1-a13c-3d88e6201bcd",
  "user_id": "c9a1e847-2f3d-4c10-b8e5-0a7d6f219abc",
  "role": "member",
  "payload": {
    "order_id": "ord_9f2a4c1e83b7",
    "status": "pending",
    "currency": "USD",
    "total": 149.99,
    "line_items": [
      {
        "sku": "SYNQ-SHIRT-M-BLK",
        "quantity": 2,
        "unit_price": 74.99
      }
    ],
    "created_at": "2024-12-04T15:32:06.998Z"
  }
}

Envelope fields

Field	Type	Description
`event_id`	string (UUID)	Unique identifier for this event instance. Use it to deduplicate deliveries.
`event_type`	string	The event category in `domain.action` format
`timestamp`	string (ISO 8601)	UTC timestamp of when the event was published
`tenant_id`	string (UUID)	The Tenant in which the event occurred
`org_id`	string (UUID)	The Organization whose action triggered the event
`user_id`	string (UUID)	The user who performed the action
`role`	string	The role of the user at the time of the action
`payload`	object	Event-specific data — structure varies by `event_type`

The event_id is unique per event. Store it and check for duplicates in your handler to make your consumer idempotent — Synq may re-deliver an event if it does not receive a successful acknowledgement from your endpoint.

Receiving events via webhooks

To start receiving events, register a webhook endpoint in your Synq dashboard or through the API. Synq will POST each matching event to your URL as it occurs.

Create a webhook endpoint

Navigate to Settings → Webhooks in the dashboard and click Add Endpoint. Enter the HTTPS URL of your listener and select the event types you want to receive.

Verify the signature

Each delivery includes a Synq-Signature header you can use to confirm the request came from Synq and was not tampered with in transit. Validate it before processing the payload.

Acknowledge with a 2xx response

Return any 2xx HTTP status code within 10 seconds to acknowledge delivery. If your endpoint returns a non-2xx status or times out, Synq retries with exponential back-off.

Process asynchronously for heavy work

If your handler needs to do significant work (database writes, third-party API calls), acknowledge the event immediately and enqueue the work for background processing. This prevents timeouts from triggering unnecessary retries.

For the full webhook setup guide, including signature verification and retry configuration, see Webhooks.

Frequently asked questions

How long does Synq retain events?

Synq retains all published events for 30 days. You can replay events within that window from the Settings → Webhooks → Event Log page in the dashboard, which is useful for debugging or recovering from a prolonged outage on your endpoint.

Can I filter events by order status or product category?

Currently, event subscriptions filter by event type. Fine-grained filtering on payload fields is on the roadmap. For now, filter in your handler after receiving the event.

Is there a rate limit on event delivery?

Synq delivers events as fast as your endpoint can acknowledge them. There is no artificial throttle, but your endpoint should respond quickly to avoid back-pressure on retries. See Webhooks for guidance on handling high-throughput scenarios.

What happens if my endpoint is down for several hours?

Synq retries failed deliveries with exponential back-off for up to 72 hours. After that window, undelivered events are marked as failed. You can replay them manually from the Event Log.

Get Started

Core Concepts

Product Catalog

Orders & Inventory

Integrations

Platform

Events: Real-Time Notifications in Synq

Why events matter

Reliable delivery

Fully auditable

Consistent structure

Tenant-isolated

Common event types

Event payload structure

Receiving events via webhooks

Frequently asked questions

​Why events matter

Reliable delivery

Fully auditable

Consistent structure

Tenant-isolated

​Common event types

​Event payload structure

​Receiving events via webhooks

​Frequently asked questions

Why events matter

Common event types

Event payload structure

Receiving events via webhooks

Frequently asked questions