Webhooks

Webhooks provide real-time notifications whenever an order or return changes state. They are designed as asynchronous notifications, not synchronous APIs.

See also: Webhook Events by State

Overview

Webhook events are emitted when specific order or return states are reached. Each event is delivered via HTTP and must be acknowledged immediately.

Delivery Flow

1. An order or return transitions to a new state
2. A webhook event is generated
3. The event is sent via HTTP POST
4. The merchant system:

• Returns HTTP 200
• Processes the event asynchronously

5. Failed deliveries are retried

Subscription

Merchants can:

1. Register a webhook URL
2. Configure a shared secret
3. Enable / disable delivery at any time

Webhook delivery starts only after successful registration.

URL Validation (Registration Check)

During registration, the platform performs a one-time endpoint validation to ensure the provided URL is usable.

What we validate

• The endpoint is reachable
• It responds with HTTP 200

Validation request

• Method: POST
• Content-Type: application/json
• Expected response: HTTP 200

Headers

• If authentication is configured, an Authorization header is included.
• The request includes a fixed User-Agent value:

User-Agent: Shopflix WebHook Test

Webhook Events

Order Events

Return Events

Webhook Request

Request Metadata

Payload Example

{
  "order_data": {
    "id": "GR--4004973--MER75",
    "eventType": "order.deliverd",
    "countryCode": "GR",
    "hasInvoice": false,
    "subTotalItemsAmount": 10,
    "totalItemsAmount": 15,
    "createdAt": "2025-12-18 07:37:03.000000",
    "updatedAt": null,
    "expiresAt": null,
    "dispatchUntil": null,
    "customer": {
      "userId": 91755,
      "email": "customer42@example.com",
      "phone": "+35799123456",
      "firstName": "Spencor",
      "lastName": "Hopkin"
    },
    "addressDetails": {
      "street": "Test",
      "streetNumber": "53",
      "postCode": "14451",
      "city": "ΜΕΤΑΜΟΡΦΩΣΗ",
      "region": "ΑΤΤΙΚΉ",
      "regionCode": "ΑΤΤ",
      "country": "Greece",
      "countryCode": "GR"
    },
    "invoiceDetails": null,
    "carrier": {
      "shipmentId": 4047769,
      "name": "Courier Center",
      "deliveryName": "Courier Center Standard",
      "deliveryKey": "courier_center_standard",
      "trackingCodes": "013791689230",
      "comments": null,
      "deliveryToCourierEstimationDate": "18/12/2025",
      "deliveryToCustomerEstimationDate": "22/12/2025"
    },
    "payment": {
      "name": "cod"
    },
    "lineItems": [
      {
        "id": 42140,
        "sku": "SF-100005366",
        "merchantEan": "sf-foo-bar-5",
        "merchantSku": "MERSKU-SF-09175005-MER75-S",
        "productName": "Κρεμαστό Φωτιστικό GloboStar 02084 Μονόφωτο Πλέγμα για Ντουί E27 Μπεζ",
        "unitPrice": 10,
        "originalUnitPrice": 10,
        "totalPrice": 10,
        "quantity": 1,
        "sfArticle39Valid": false,
        "giftWrap": false,
        "extendedAttributes": {
          "originalValue": ""
        }
      }
    ]
  },
  "timestamp_webhook_creation": "2025-12-18 08:08:37",
  "timestamp_webhook_submission": "2025-12-18 08:08:41",
  "merchant_webhook_data": null
}

Payload Reference

Top-level Fields

Order

Customer

Line Items

Carrier

Processing Guidelines

• Return HTTP 200 immediately
• Process events asynchronously
• Handle duplicate deliveries safely

Failure Handling & Retries

What is considered a failure?

A delivery attempt fails if:

• The request times out
• The endpoint returns anything other than HTTP 200

Automatic retries

• Failed deliveries are retried automatically - Retries happen

within a short time window

• The same payload is sent every time

Manual resend (Planned capability)

Manual re-delivery of webhook events is a planned feature.

Once available, merchants will be able to manually trigger a re-delivery of previous webhook events from the Merchant Portal.

Manual resend:

When implemented:

• The original payload will be reused
• No data will be recalculated or modified
• Manual re-delivery will follow the same delivery rules as automatic retries

Idempotency Because retries and manual resends are possible:

• The same event may be delivered more than once
• Merchants must treat webhook delivery as at‑least‑once

Recommended strategies:

• Store a unique event key (eventType + orderId + eventTime)
• Ignore already‑processed events - Never rely on delivery count

Security

Registration vs Event Delivery

Registration validation (one-time)

• Uses a fixed User-Agent: Shopflix WebHook Test
• Expects HTTP 200
• Does not include X-Data-Signature

Monitoring

• Signature validation failures
• 5xx responses
• Delayed processing
• Duplicate event deliveries