Webhooks

Webhooks allow you to receive events as HTTP POST requests to a server when events occur in Quartzy. See Wikipedia for more information on the basics of a webhook.

Managing Webhooks in Quartzy

Refer to this user guide on how to manage webhook configurations from the lab settings in Quartzy.

Message Format

All Quartzy Webhooks follow the Cloud Events v1 specification. There is a common envelope containing metadata such as the event type and time, with a common data key that contains the event data. Every event will contain only a single key within the data matching the resource type for the given event.

Every event type begins with com.quartzy, followed by the resource type name, ending with the event type on that resource. For example, the type for the event that occurs when a Quartzy Shop Order Item is Shipped will be com.quartzy.sales-order-item.shipped. The data included in this event will be the Quartzy Shop order item that was shipped.

Signature

By default, Quartzy includes an HMAC-SHA256 signature in the Signature header of all webhook requests. When creating a webhook, a secret will be generated and displayed to the user. This secret may be used to validate the signature to ensure Quartzy is was the sender of the received request.

Server TLS Verification

When sending a webhook to an https:// URL, Quartzy will validate the TLS Certificate of the server to ensure secure communication with the receiver.

Error Handling and Retries

Each successful call to a webhook should reply with a status code in the 200-299 range. Any response code outside this range will be treated as an error. Additionally, any request taking longer than 3 seconds will be considered an error. Please ensure you return a successful response before this timeout period.

In the event of error or timeout, a webhook will be retried up to 3 times. The first retry will be attempted after 10 seconds, the second after 100 seconds, and the third after 1000 seconds.