Events

Server

Read the Event Log

GET

https://api.wocart.store

/api/events

X-API-Key (header)

The store's Business Events. With after, oldest first from that Sequence: follow the log by passing each page's nextCursor as the next after. Otherwise newest first, paged back with before.

Read the Event Log › query Parameters

after

integer | null · min: 0

Read forward, oldest first, from after this Sequence — how an integration follows the log (after=0 reads from the start).

before

integer | null · min: 0

Read back, newest first, from before this Sequence.

limit

integer · min: 1 · max: 100

At most this many events (1–100)

Default: 50

type

string

Only these Event Types, comma-separated, each named exactly (order.confirmed), by subject (order.*), or *.

orderId

string · minLength: 1

Only the events of this order

Read the Event Log › Responses

A page of the Event Log

success

boolean · required

BusinessEvent[] · required

count

integer · required

Number of items returned

nextCursor

integer | null · required

The Sequence to pass as after (or before, the way this page was read) for the next page; null on the last page

GET/api/events

curl https://api.wocart.store/api/events \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "id",
      "sequence": 0,
      "type": "order.created",
      "version": 0,
      "subject": {
        "type": "order",
        "id": "id"
      },
      "orderId": "orderId",
      "occurredAt": "2024-08-25T15:00:00Z",
      "recordedAt": "2024-08-25T15:00:00Z",
      "actor": {
        "kind": "staff",
        "id": "id",
        "name": "name"
      },
      "origin": "dashboard",
      "data": {
        "order": {
          "id": "id",
          "number": "number",
          "status": "new",
          "type": "online",
          "placedAt": "2024-08-25T15:00:00Z",
          "locale": "ar",
          "customer": {
            "id": "id",
            "name": "name",
            "phone": "phone",
            "email": "email"
          },
          "destination": {
            "wilaya": {
              "id": 0,
              "name": "name",
              "nameAr": "nameAr"
            },
            "commune": {
              "id": "id",
              "name": "name",
              "nameAr": "nameAr"
            },
            "city": "city",
            "address": "address",
            "deliveryType": "home",
            "stationCode": "stationCode"
          },
          "lines": [
            {
              "id": "id",
              "productId": "productId",
              "variantId": "variantId",
              "name": "name",
              "variantLabel": "variantLabel",
              "sku": "sku",
              "quantity": 0,
              "unitPrice": {
                "amount": "amount",
                "currency": "DZD"
              },
              "discount": {
                "amount": "amount",
                "currency": "DZD"
              },
              "total": {
                "amount": "amount",
                "currency": "DZD"
              },
              "gift": true,
              "offer": {
                "id": "id",
                "name": "name"
              },
              "returnedQuantity": 0
            }
          ],
          "subtotal": {
            "amount": "amount",
            "currency": "DZD"
          },
          "deliveryFee": {
            "amount": "amount",
            "currency": "DZD"
          },
          "total": {
            "amount": "amount",
            "currency": "DZD"
          },
          "coupon": {
            "code": "code",
            "discount": {
              "amount": "amount",
              "currency": "DZD"
            }
          },
          "freeDeliveryOffer": {
            "id": "id",
            "name": "name"
          },
          "notes": "notes",
          "customFields": [
            {
              "id": "id",
              "label": "label",
              "type": "text",
              "value": "value"
            }
          ]
        }
      }
    }
  ],
  "count": 0,
  "nextCursor": 0
}

json

application/json

Get a Business Event

GET

https://api.wocart.store

/api/events/{id}

X-API-Key (header)

Get a Business Event › path Parameters

id

string · required

Resource ID

Get a Business Event › Responses

The Business Event

success

boolean · required

BusinessEvent · required

A Business Event as it is published: its envelope — id (the same on every delivery), Sequence, type and version, subject, order, when it happened and was recorded, who caused it and through what — and the data its type and version promise. Fields are only ever added.

GET/api/events/{id}

curl https://api.wocart.store/api/events/:id \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "id": "id",
    "sequence": 0,
    "type": "order.created",
    "version": 0,
    "subject": {
      "type": "order",
      "id": "id"
    },
    "orderId": "orderId",
    "occurredAt": "2024-08-25T15:00:00Z",
    "recordedAt": "2024-08-25T15:00:00Z",
    "actor": {
      "kind": "staff",
      "id": "id",
      "name": "name"
    },
    "origin": "dashboard",
    "data": {
      "order": {
        "id": "id",
        "number": "number",
        "status": "new",
        "type": "online",
        "placedAt": "2024-08-25T15:00:00Z",
        "locale": "ar",
        "customer": {
          "id": "id",
          "name": "name",
          "phone": "phone",
          "email": "email"
        },
        "destination": {
          "wilaya": {
            "id": 0,
            "name": "name",
            "nameAr": "nameAr"
          },
          "commune": {
            "id": "id",
            "name": "name",
            "nameAr": "nameAr"
          },
          "city": "city",
          "address": "address",
          "deliveryType": "home",
          "stationCode": "stationCode"
        },
        "lines": [
          {
            "id": "id",
            "productId": "productId",
            "variantId": "variantId",
            "name": "name",
            "variantLabel": "variantLabel",
            "sku": "sku",
            "quantity": 0,
            "unitPrice": {
              "amount": "amount",
              "currency": "DZD"
            },
            "discount": {
              "amount": "amount",
              "currency": "DZD"
            },
            "total": {
              "amount": "amount",
              "currency": "DZD"
            },
            "gift": true,
            "offer": {
              "id": "id",
              "name": "name"
            },
            "returnedQuantity": 0
          }
        ],
        "subtotal": {
          "amount": "amount",
          "currency": "DZD"
        },
        "deliveryFee": {
          "amount": "amount",
          "currency": "DZD"
        },
        "total": {
          "amount": "amount",
          "currency": "DZD"
        },
        "coupon": {
          "code": "code",
          "discount": {
            "amount": "amount",
            "currency": "DZD"
          }
        },
        "freeDeliveryOffer": {
          "id": "id",
          "name": "name"
        },
        "notes": "notes",
        "customFields": [
          {
            "id": "id",
            "label": "label",
            "type": "text",
            "value": "value"
          }
        ]
      }
    }
  }
}

json

application/json

List Consumers

GET

https://api.wocart.store

/api/event-consumers

X-API-Key (header)

Who receives the store's Business Events, with how many Deliveries are on their way and how many were given up on.

List Consumers › Responses

200

Every Consumer, oldest first

success

boolean · required

EventConsumer[] · required

count

integer · required

Number of items returned

GET/api/event-consumers

curl https://api.wocart.store/api/event-consumers \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "id",
      "kind": "webhook",
      "name": "name",
      "enabled": true,
      "builtIn": true,
      "subscription": [
        "order.created",
        "shipment.delivered"
      ],
      "catalogueVersion": 0,
      "disabledReason": "failing",
      "failingSince": "failingSince",
      "deliveries": {
        "due": 0,
        "dead": 0
      },
      "webhook": {
        "url": "url",
        "signingSecret": "••••Xw4=",
        "secretRotatedAt": "2024-08-25T15:00:00Z",
        "previousSecretSignsUntil": "2024-08-25T15:00:00Z"
      },
      "createdAt": "createdAt",
      "updatedAt": "updatedAt"
    }
  ],
  "count": 0
}

json

application/json

Add a webhook

POST

https://api.wocart.store

/api/event-consumers

X-API-Key (header)

A webhook Consumer: an endpoint of the merchant's own that receives the Business Events it subscribes to, recorded from now on, each POSTed as JSON and signed per the Standard Webhooks specification. Its Signing Secret is in this answer and never shown in full again.

Add a webhook › Request Body

kind

string · enum · required

The kind of Consumer: webhook, an endpoint of the merchant's own

Enum values:

webhook

name

string · minLength: 1 · maxLength: 80 · required

What the merchant calls it

url

string · required

Where Deliveries are POSTed: a public https URL

subscription

string[] · minItems: 1 · maxItems: 20 · required

The Event Types it receives, each named exactly, by subject (order.*), or *

Add a webhook › Responses

The webhook, and its Signing Secret

success

boolean · required

WebhookCreated · required

POST/api/event-consumers

curl https://api.wocart.store/api/event-consumers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "kind": "webhook",
  "name": "Order system",
  "url": "https://erp.example.dz/hooks/wocart",
  "subscription": [
    "order.created",
    "shipment.*"
  ]
}'

Example Request Body

{
  "kind": "webhook",
  "name": "Order system",
  "url": "https://erp.example.dz/hooks/wocart",
  "subscription": [
    "order.created",
    "shipment.*"
  ]
}

json

Example Responses

{
  "success": true,
  "data": {
    "consumer": {
      "id": "id",
      "kind": "webhook",
      "name": "name",
      "enabled": true,
      "builtIn": true,
      "subscription": [
        "order.created",
        "shipment.delivered"
      ],
      "catalogueVersion": 0,
      "disabledReason": "failing",
      "failingSince": "failingSince",
      "deliveries": {
        "due": 0,
        "dead": 0
      },
      "webhook": {
        "url": "url",
        "signingSecret": "••••Xw4=",
        "secretRotatedAt": "2024-08-25T15:00:00Z",
        "previousSecretSignsUntil": "2024-08-25T15:00:00Z"
      },
      "createdAt": "createdAt",
      "updatedAt": "updatedAt"
    },
    "signingSecret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

json

application/json

Get a Consumer

GET

https://api.wocart.store

/api/event-consumers/{id}

X-API-Key (header)

Get a Consumer › path Parameters

id

string · required

Resource ID

Get a Consumer › Responses

The Consumer

success

boolean · required

EventConsumer · required

Change a Consumer

PATCH

https://api.wocart.store

/api/event-consumers/{id}

X-API-Key (header)

Start or stop any Consumer; rename a webhook, point it at another URL or change what it subscribes to. Stopped, a Consumer receives nothing: its waiting Deliveries are skipped and new events are not delivered to it. Started again, it receives what is recorded from then on and its failing streak is cleared; replay what it missed. A new Subscription applies to what is recorded from then on; a new URL starts without a failing streak.

Change a Consumer › path Parameters

id

string · required

Resource ID

Change a Consumer › Request Body

enabled

boolean

Start (true) or stop (false) delivering to it

name

string · minLength: 1 · maxLength: 80

What the merchant calls it

url

string

Where Deliveries are POSTed: a public https URL

subscription

string[] · minItems: 1 · maxItems: 20

The Event Types it receives, each named exactly, by subject (order.*), or *

Change a Consumer › Responses

The Consumer as it now stands

success

boolean · required

EventConsumer · required

PATCH/api/event-consumers/{id}

curl https://api.wocart.store/api/event-consumers/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "enabled": true,
  "name": "Order system",
  "url": "https://erp.example.dz/hooks/wocart",
  "subscription": [
    "order.created",
    "shipment.*"
  ]
}'

Example Request Body

{
  "enabled": true,
  "name": "Order system",
  "url": "https://erp.example.dz/hooks/wocart",
  "subscription": [
    "order.created",
    "shipment.*"
  ]
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "id",
    "kind": "webhook",
    "name": "name",
    "enabled": true,
    "builtIn": true,
    "subscription": [
      "order.created",
      "shipment.delivered"
    ],
    "catalogueVersion": 0,
    "disabledReason": "failing",
    "failingSince": "failingSince",
    "deliveries": {
      "due": 0,
      "dead": 0
    },
    "webhook": {
      "url": "url",
      "signingSecret": "••••Xw4=",
      "secretRotatedAt": "2024-08-25T15:00:00Z",
      "previousSecretSignsUntil": "2024-08-25T15:00:00Z"
    },
    "createdAt": "createdAt",
    "updatedAt": "updatedAt"
  }
}

json

application/json

Delete a webhook

DELETE

https://api.wocart.store

/api/event-consumers/{id}

X-API-Key (header)

The webhook goes with its Deliveries and their Attempts. The Business Events stay in the Event Log.

Delete a webhook › path Parameters

id

string · required

Resource ID

Delete a webhook › Responses

Deleted

MessageResponse

success

boolean · required

message

string · required

Rotate a webhook's Signing Secret

POST

https://api.wocart.store

/api/event-consumers/{id}/rotate-secret

X-API-Key (header)

A new Signing Secret, in this answer and never shown in full again. For a day, Deliveries carry a signature by each secret, so the endpoint switches to the new one without refusing any; after that, only the new one signs.

Rotate a webhook's Signing Secret › path Parameters

id

string · required

Resource ID

Rotate a webhook's Signing Secret › Responses

The new Signing Secret

success

boolean · required

SigningSecret · required

Send a Test Event to a webhook

POST

https://api.wocart.store

/api/event-consumers/{id}/test

X-API-Key (header)

POSTs an example of an Event Type to the webhook now, signed like any Delivery, and answers what the endpoint did. A Test Event has Sequence 0 and an id starting test_; it is recorded in no Event Log and has no Delivery. It is sent to a stopped webhook too.

Send a Test Event to a webhook › path Parameters

id

string · required

Resource ID

Send a Test Event to a webhook › Request Body

type

string · enum

Which Event Type's example to send; order.created when not said

Enum values:

order.created

order.updated

order.confirmed

order.unreachable

order.preparing

order.ready

order.cancelled

order.line_returned

Send a Test Event to a webhook › Responses

What the endpoint did with it

success

boolean · required

WebhookTest · required

Replay Business Events to a Consumer

POST

https://api.wocart.store

/api/event-consumers/{id}/replay

X-API-Key (header)

Deliver the Business Events of a Sequence range again to this Consumer — those it subscribes to now. Settled Deliveries become due with their Attempts started over (their history is kept); events it never received, recorded while it was stopped or before it existed, get a Delivery. One already on its way is left alone. No Business Event is recorded again.

Replay Business Events to a Consumer › path Parameters

id

string · required

Resource ID

Replay Business Events to a Consumer › Request Body

fromSequence

integer · min: 1 · required

The first Business Event to deliver again, by Sequence

toSequence

integer · min: 1 · required

The last one; at most 1000 Sequences after the first

Replay Business Events to a Consumer › Responses

Accepted: the Deliveries are due and the store delivers them

success

boolean · required

Redelivery · required

List Deliveries

GET

https://api.wocart.store

/api/event-deliveries

X-API-Key (header)

A Consumer's Deliveries, newest event first and paged with before, or every Delivery of one Business Event. state=dead lists those given up on.

List Deliveries › query Parameters

consumerId

string · minLength: 1

A Consumer's Deliveries, newest event first

eventId

string · minLength: 1

Every Delivery of one Business Event

state

string · enum

Only Deliveries in this state — dead for those given up on

Enum values:

due

delivered

skipped

dead

before

integer | null · min: 0

Read on from before this event Sequence: the previous page's nextCursor

limit

integer · min: 1 · max: 100

At most this many (1–100)

Default: 50

List Deliveries › Responses

A page of Deliveries

success

boolean · required

EventDelivery[] · required

count

integer · required

Number of items returned

nextCursor

integer | null · required

Pass as before for the next page; null on the last page

Get a Delivery

GET

https://api.wocart.store

/api/event-deliveries/{id}

X-API-Key (header)

The Delivery with every Attempt it took and what the Consumer answered.

Get a Delivery › path Parameters

id

string · required

Resource ID

Get a Delivery › Responses

The Delivery

success

boolean · required

EventDeliveryDetail · required

GET/api/event-deliveries/{id}

curl https://api.wocart.store/api/event-deliveries/:id \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "id": "id",
    "consumerId": "consumerId",
    "state": "due",
    "attempts": 0,
    "nextAttemptAt": "nextAttemptAt",
    "lastError": "lastError",
    "createdAt": "createdAt",
    "settledAt": "settledAt",
    "event": {
      "id": "id",
      "sequence": 0,
      "type": "order.created",
      "orderId": "orderId",
      "occurredAt": "occurredAt"
    },
    "attemptLog": [
      {
        "attempt": 0,
        "attemptedAt": "attemptedAt",
        "durationMs": 0,
        "outcome": "delivered",
        "httpStatus": 0,
        "responseExcerpt": "responseExcerpt",
        "error": "error"
      }
    ]
  }
}

json

application/json

Retry a Delivery

POST

https://api.wocart.store

/api/event-deliveries/{id}/retry

X-API-Key (header)

Make a settled Delivery — dead, skipped or delivered — due again now, its Attempts started over; its history is kept.

Retry a Delivery › path Parameters

id

string · required

Resource ID

Retry a Delivery › Responses

Accepted: the Delivery is due and the store delivers it

success

boolean · required

Redelivery · required

Apps Users