How Events & Webhooks Work

With a basic understanding About Events & Webhooks let's see exactly how they work using the "CreateOrderEvent".

  1. A Webhook is coded with custom logic in an endpoint in a Client Web Application

    Learn how to Code A Webhook

  2. The Webhook is configured so the endpoint is subscribed to the CreateorderEvent.

    Learn how to Configure A Webhook

  3. A customer places an order on the site.

    A "CreateOrderEvent" is created.

  4. Directscale sends the webhook endpoint an HTTP POST payload with the information of the CreateOrderEvent.

    See an example of an HTTP POST Payload

Continous Polling vs. Webhook Subscriptions

Webhooks are a performant alternative to continuous polling. Figure 1 shows the comparison using the Order Created event.


Figure 1: An image showing two sequence diagrams to show the performance difference between Continous Polling and Webhook Subscriptions



The HTTP POST payload to a Client Web Application will include

  • URL
    • the endpoint of the Client Web Application that will receive the Event data and implement custom logic
  • Headers
    • ContentType | "application/json; charset=UTF-8"
    • Authorization | bearer token used by Client Web Applications to authorize the requests. See Securing Client Web Applications for more details
    • X-Directscale-Client-Id | "The unique ID for the client"
    • X-Directscale-Message-Id | "A unique ID that can be used to ignore duplicate messages "
    • X-Directscale-User | "The username of the user who initiated the call. Only included when the user context is available"
  • Body
    • Relevant data to the Event in a JSON format
    • All JSON bodies will have the EventDateUtc and EventType properties

Example of an HTTP POST payload to a Client Web Application

curl --location --request POST '' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Authorization: Bearer mcwod!j9xn2fylqo%2692kd09$jdi1l' \
--data-raw '{

📝Parameter definitions:

  • OrderStatus – “Paid”, “Pending Payment”, etc.
  • OrderTypes – Standard=1, AutoShip=2. Learn more about Order Types.
  • ClientId – Your company unique identifier found in your Admin URL ({Client_ID}
  • AssociateId vs. BackOfficeId – Learn the difference in Understanding Platform IDs
  • DistributorId – Refers to the Associate's numerical Associate ID (also known as the DirectScale ID).

Custom Events

Client developers can trigger custom events inside of a Process Hook to offload processing that could be done asynchronously instead of in-process. Use the EventService.PostEvent Extension API to trigger a custom event.


Using the C# Client Library?

You can use the IEventService in the C# Client Library to call the Extension API.