Webhooks

Webhooks are used to handle real-time updates, such as when the status of an order changes. They consist of a URL that Merchrocket calls along with the data of the updated object.

Example

One of the most important cases where a webhook is used is when the status of an order changes, particularly when it is being shipped. If you have a webhook URL associated with your account, we will trigger that webhook URL via a POST request containing the relevant IDs and, if applicable, the current status of the updated item.

POST /webhook HTTP/1.0
Host: shop.example.org
Accept: */*
User-Agent: Merchrocket,
Content-Type: application/json,
X-Account-Id: 018ecd62-1e90-75a8-95c6-484bd9edbce0,
X-Webhook-Id: 018f75d1-9a33-7a75-bb4a-151e5961b4cc,
X-Merchrocket-Request-Signature: 47b17191d508b5e88f7a419cccebefbadfb21ffe8f55c7995a7e590461a21c85,
X-Merchrocket-Request-Timestamp: 1715668621

{
  "data": {
    "order": {
      "id": "018f3daa-d32a-777f-bb42-7623778f10aa",
      "status": "shipped",
      "external_id": "OFC4IC5F",
    }
  },
  "type": "order.updated",
  "retries": 0,
  "occurred_at": "2024-05-14T06:37:00+00:00"
}

Supported webhooks

Orders API

The Orders API calls a webhook when the order is created or reaches one of the following statuses:

• pending
• canceled
• failed
• inprocess
• onhold
• partial
• fulfilled

Read more about the order workflow and status changes.

Order webhook payload example.

{
  "data": {
    "order": {
      "id": "0191e506-afa4-73e7-b6a4-74ef2e8f5c2c",
      "status": "draft",
      "created_at": "2024-09-12T06:58:26+00:00",
      "updated_at": "2024-09-12T06:58:26+00:00",
      "external_id": "YOW-77927432323432",
      "dashboard_url": "",
      "organization_id": "0191b6b7-5fd0-73ad-a991-e91719445b52"
    }
  },
  "type": "order.created",
  "retries": 0,
  "occurred_at": "2024-09-12T06:58:26+00:00"
}

Mockup API

The Mockups API calls a webhook when the order is created or reaches one of the following statuses:

• pending (Mockup Generator task is still being processed.)
• completed (Mockup Generator task was successfully processed.)
• failed (Mockup Generator task failed.)

Read more about mockups and status changes.

Mockups webhook payload example.

{
  "data": {
    "mockupTask": {
      "id": "0191b1cf-6024-77c3-8bc2-3ae6ad7eb633",
      "status": "completed",
      "createdAt": "2024-09-02T08:17:23+00:00",
      "finishedAt": "2024-09-02T08:17:23+00:00",
      "failureReasons": [],
      "catalogVariantMockups": [
        {
          "mockups": [
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-1-2261fc3c1983aad1f9027205ccb3247f4f65aa6a.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-1"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-2-2261fc3c1983aad1f9027205ccb3247f4f65aa6a.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-2"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-3-2261fc3c1983aad1f9027205ccb3247f4f65aa6a.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-3"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-4-2261fc3c1983aad1f9027205ccb3247f4f65aa6a.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-4"
            }
          ],
          "catalogVariantId": "590f1af7-75f6-46c8-bab3-60b109a66371"
        },
        {
          "mockups": [
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-1-d002f5ef9cfdb9a879569324b1c820c6b312cfb5.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-1"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-2-d002f5ef9cfdb9a879569324b1c820c6b312cfb5.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-2"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-3-d002f5ef9cfdb9a879569324b1c820c6b312cfb5.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-3"
            },
            {
              "mockupUrl": "https://dbcq9of27g5zl.cloudfront.net/mockup_heart_mug_all_colors-mockup-4-d002f5ef9cfdb9a879569324b1c820c6b312cfb5.jpg",
              "placement": "main",
              "technique": "direct_print",
              "displayName": "mockup-4"
            }
          ],
          "catalogVariantId": "96870bc1-08c8-488b-9ed2-f921a7452629"
        }
      ]
    }
  },
  "type": "mockup_task.finished",
  "retries": 0,
  "occurredAt": "2024-09-02T08:17:23+00:00"
}

Shipments API

The Shipments API calls a webhook when the shipment is created or reaches one of the following statuses:

• pending(The shipment label is created but the package not labelled.)
• canceled (The shipment was canceled.)
• packaged (The shipment is packed and labelled with the shipment label.)
• shipped (The shipment is on its way to the customer and has been handed over to the service provider (carrier).)
• returned(The parcel could not be delivered and has been returned to Merchrocket.)

Read more about shipments.

Shipment webhook payload example.

{
  "data": {
    "shipment": {
      "id": "0191b37b-2681-7f60-a156-9de12ed5caf7",
      "carrier": "DHL",
      "orderId": "0191b26d-2fe9-7b76-9fde-480aa71ed8b3",
      "service": "STANDARD",
      "shippedAt": "2024-09-02T18:04:36+00:00",
      "trackingId": "00340434494996194681",
      "trackingUrl": "https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=dhl_de&code=00340434494996194681&destination=DE&lang=de-de&source=DE&type=parcel&verification=30823&servicepoint_verification=&shipping_product_code=dhl_de%3Adhl_paket&created_at=2024-09-02",
      "shipmentStatus": "shipped"
    }
  },
  "type": "shipment.created",
  "retries": 0,
  "occurred_at": "2024-09-02T16:04:38+00:00"
}

Security

Merchrocket uses a secret to generate a hash signature for API events.

This signature is transmitted in the X-Merchrocket-Request-Signature request header and allows you to authenticate that the API event request is from Merchrocket and not from an unauthorised source.

To verify the signature, follow these steps

• Determine the original signature and timestamp from the request headers: X-Merchrocket-Request-Signature and X-Merchrocket-Request-Timestamp.
• Prepare the event payload by concatenating the timestamp and the request body with a dot ( .).
• Generate a hash signature (HMAC SHA256) of the event payload using the secret.
• Compare the original and generated signatures.

Example of signature verification with PHP

// Secret key used for generating the hash signature.
$secret = "3ha6eonoa9icsckw8kccos084w0c0000g08g40oo4kww0gc8w4";

// Original signature received in the X-Merchrocket-Request-Signature header.
$originalSignature = "47b17191d508b5e88f7a419cccebefbadfb21ffe8f55c7995a7e590461a21c85";

// Timestamp extracted from the X-Merchrocket-Request-Timestamp header.
$timestamp = "1715668621";

// The complete request body containing data.
$requestBody = '{ "data": { "order": { ... }, "type": "order.updated", ...}'

// Concatenate timestamp and request body to prepare the event payload.
$signedPayload = $timestamp . "." . $requestBody;

// Generate a hash signature using HMAC SHA256 algorithm.
$generatedSignature = hash_hmac("sha256", $signedPayload, $secret);

// Compare the original and generated signature for validation.
if (false === hash_equals($originalSignature, $generatedSignature)) {
  throw new \Exception("Invalid signature");
}

You can also use the X-Merchrocket-Request-Timestamp to check if the event is too old.

Retry Strategy

When Merchrocket calls your webhook, simply return the HTTP status 200 OK to indicate that your system has successfully processed the request. Merchrocket will interpret this response as confirmation of correct processing.

If you experience a temporary problem with your hosting service and return a different status, Merchrocket will continue to attempt to deliver the webhook for a few minutes so that you can process it when your hosting service is restored.

Please note that our webhook requests have a 60-second timeout. If your response exceeds this timeout by even one second, Merchrocket will consider the call to have failed and will try again later.

We will make a total of 6 attempts to deliver the webhook, with each subsequent attempt occurring at increasingly longer intervals. If we still do not receive a 200 OK response after the 6th attempt (after 17 minutes), we will stop further attempts.