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.

14521452

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


Payloads


📘

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 'https://acme.clientextension.directscale.com/api/webhookRecieverEndpoint' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Authorization: Bearer mcwod!j9xn2fylqo%2692kd09$jdi1l' \
--data-raw '{
    "OrderNumber":1,
    "OrderPaymentId":1,
    "PaymentStatus":"Paid",
    "PaymentType":"Charge",
    "Amount":20.0,
    "CurrencyCode":"USD",
    "EventDateUtc":"2021-10-12T18:07:26.8794398Z",
    "EventCategory":"OrderEvents",
    "EventType":"CreateOrderPaymentEvent",
}'

📝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}.directscale.com)
  • 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.


Did this page help you?