Skip to main content
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 typeTriggered when
order.createdA new order is placed or imported into Synq
order.updatedAn existing order’s status, line items, or details change
product.createdA new product is added to your catalog
product.updatedA product’s price, description, or attributes are modified
inventory.adjustedStock levels change due to a sale, return, or manual adjustment
integration.syncedA 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
FieldTypeDescription
event_idstring (UUID)Unique identifier for this event instance. Use it to deduplicate deliveries.
event_typestringThe event category in domain.action format
timestampstring (ISO 8601)UTC timestamp of when the event was published
tenant_idstring (UUID)The Tenant in which the event occurred
org_idstring (UUID)The Organization whose action triggered the event
user_idstring (UUID)The user who performed the action
rolestringThe role of the user at the time of the action
payloadobjectEvent-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.
1

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.
2

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.
3

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.
4

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

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.
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.
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.
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.