Ping

A request we send to you whenever there are new changes.

Request

Headers

Fields

Every API key can optionally be assigned a ping endpoint. You can configure these endpoints in the dashboard.

• Shop API keys receive pings for that shop.
• User API keys receive pings for all shops the user has access to.
• Partner API keys receive pings for all shops owned by the partner.

When you receive the ping request you can verify its authenticity using the X-Signature header:

if Base64(HMAC-SHA2-256(body, apikey)) ≠ headers["X-Signature"] then
    Log("Warning: Invalid ping signature!")
    exit
end if

For our mutual benefit, we include the maximum "seq" value at the time of the ping in the request body. That way, you can compare it to the "seq" value you received from the last successful call to seq and, if the value received in the ping is less than or equal to it, avoid calling seq, thus saving us both an unnecessary request:

ping := JSONDecode(body)
if ping.seq > localSeq then
    Synchronize()
end if

Response

It is not required to respond to a ping request, and we only wait approximately 7 seconds for a response to arrive. Pings are sent continuously, not just once after the "seq" value increases, so it is perfectly safe to not respond.

You can "acknowledge" a ping by responding with a single line containing either:

ok

or

ok: free form text

This will stop pings from being sent until the "seq" value changes.

The first line of the ping response is visible in your logs and can be a useful debugging tool.