Syncor

Overview

What Syncor sends, how a delivery works and how to go live.

Syncor sends webhooks to tell your systems when something happens to your orders: a sales order is created for your purchase request, a delivery note or an invoice becomes available, or the catalog changes. You set up each subscription in the developer portal: the event type, your endpoint URL, how we authenticate, and optionally a mapping profile that shapes the body.

How a delivery works

  1. Something happens in Syncor, for example an invoice is recorded for one of your orders. We record it once as a business event with its own event ID.
  2. Each of your active subscriptions for that event type gets its own delivery of the event.
  3. We build the body (the standard body, or the one your mapping profile defines), sign it, and POST it to your endpoint.
  4. Any 2xx response marks the delivery as delivered. Anything else is retried with growing intervals until it succeeds.

You can follow every step in the developer portal: Business events shows each event once, and Delivery activity shows every delivery and each attempt.

Going live

  1. Build a receiver that accepts an HTTPS POST, checks the signature, stores the event and answers 2xx quickly. See Authentication and signatures.
  2. Choose how we authenticate. For OAuth 2.0 (Microsoft Entra), add an OAuth connection in the developer portal first.
  3. Create a subscription for each event type you need, with your endpoint URL and authentication. Keep the signing secret it shows you: it is shown once.
  4. Optionally, add a mapping profile to shape the body. See Mapping profiles.
  5. Send test event on the subscription and check that your receiver accepts it. Delivery activity shows the response we got.
  6. Activate the subscription. New events of its type are sent from then on.

Creating and changing subscriptions needs the Integration Manager role and two-factor authentication on your portal account.

What we send

Each delivery is an HTTPS POST to your endpoint with the body as JSON (application/json) or, when your mapping profile produces it, CSV. Every request carries these headers:

Header Meaning
X-Syncor-Event-Id The event ID. The same on every retry and replay.
X-Syncor-Event-Type For example sales_order.created.
X-Syncor-Event-Version The payload version, currently 1.0.
X-Syncor-Delivery-Id Our ID for this delivery. Quote it to Syncor support.
X-Syncor-Timestamp When this attempt was sent, ISO 8601 in UTC.
X-Syncor-Payload-Format json or csv.
Idempotency-Key The event ID and your subscription ID, joined by a colon.
X-Syncor-Signature When your subscription has a signing secret. See Authentication and signatures.
Authorization When your subscription uses a bearer token or OAuth 2.0.

Catalog batch parts also carry X-Syncor-Batch-Id, X-Syncor-Batch-Part, X-Syncor-Batch-Parts, X-Syncor-Cursor-From, X-Syncor-Cursor-To and X-Syncor-Payload-SHA256.

The body of each event type, field by field, is on Events.