Webhooks overview

Event types

A shop can subscribe to the following event types. Each has its own page with the full payload.

A shop receives an event from three kinds of destination:

1. Webhook subscriptions. Subscriptions scoped to the shop, created from the dashboard. Each subscription = one event type + one URL + one secret (secureToken).
2. External-app destinations. An active external app (Shopify middleware, PrestaShop, WooCommerce…) whose configuration holds webhookValidateOrderUrl receives order_confirmed, and one with webhookCancelBookingUrl receives order_booking_cancelled. These have no webhook subscription: the app configuration is the subscription.
3. LEGACY -~~ Order URLs.~~~~ The urls.success given when the order was created receives the order_confirmed payload (see order success URL). The other order URLs and the discount-code URL are request/response callbacks, documented in shop integration callbacks. ~~

Delivery

Every event listed above goes out through the GreenLeaze webhook gateway.

Request

POST <destination url>
Content-Type: application/json
User-Agent: GreenLeaze-Webhook-Gateway/1.0
X-Webhook-Delivery-Id: <uuid>
X-Webhook-Signature: <base64 HMAC-SHA256 of the raw body>   (only when a secret is set)

<JSON payload>

The event type is in neither the body nor the headers. A destination knows what it receives from its subscription: register one URL per event type, or put the event type in the URL (path or query string).

Signature

Sign the raw request bytes. Re-serialising parsed JSON can reorder keys or change number formatting and break the comparison.

import { createHmac, timingSafeEqual } from 'crypto';

export function isGreenLeazeSignatureValid(params: {
  rawBody: Buffer;
  signature: string | undefined;
  secret: string;
}): boolean {
  if (!params.signature) return false;
  const expected = createHmac('sha256', params.secret)
    .update(params.rawBody)
    .digest();
  const received = Buffer.from(params.signature, 'base64');
  return (
    received.length === expected.length && timingSafeEqual(received, expected)
  );
}

Responses and retries

• The attempt count is the destination's maxAttempts which is 8 by default.
• Delivery is at least once: deduplicate on X-Webhook-Delivery-Id.
• A delivery replayed from the dashboard ("relancer") is a new delivery with a new X-Webhook-Delivery-Id. Make the handler idempotent on business keys as well, for example id + event type.
• Delivery logs are visible in your GreenLeaze Dashboard

Which destinations an event reaches

GreenLeaze selects the active webhook subscriptions of the event's shop, then filters them on the order's origin, read from the payload's source field. External-app destinations are not filtered this way (see order_confirmed for their own rule).

Delayed and held deliveries

• LEGACY - Order success URL. A webhook_delay configured for the shop and the order's source turns the call into a scheduled delivery, sent after delayInMinutes.
• Held until the manual-validation decision. An external-app destination whose app has delayWebhookUntilAutoApproval receives order_confirmed late when a manual validation is open on the order. The delivery is scheduled for the auto-approval time + 24 h, released at once if the order is approved, and cancelled if the order is rejected.

Conventions

Order status

draft · deposit_paid · validating · active · inactive · canceled · canceled_with_fees · finished

Order shopStatus

not-opened · opened · account-selected · pending-additional-information · rejected · bank-selected · bank-connected · pending-company-validation · draft · canceled · finished · payment-method-entered · adresses-entered · customer-created · accepted-pending-customer-validation · active

An order that enters validation (status: "validating") is already shopStatus: "active": product decision, shops see the order as active from that point.