Custom API Integration | Sign Customiser Help Center

This guide will walk you through the process of integrating your custom ecommerce store with Sign Customiser, allowing your customers to design custom signs directly on your website.

Overview

The integration consists of two main components:

Product Creation Flow: When a customised sign is created, we'll notify your system and you'll provide us with a product ID
Order Processing: When an order is placed, you'll send the order details to our API for processing

Part 1: Setting Up the Integration in Sign Customiser

Step 1: Access Integration Settings

Log into your Sign Customiser account
From the home screen click on "Tools" -> "Integrations"
Find the Custom Integration card and click "Connect Custom Integration"

Step 2: Configure Your Webhook URL

Enter the full URL where we should POST when a product is created
- This should be an endpoint on your server that can receive and process product data
- Example: https://yourstore.com/api/sign-customiser/products
Save the integration

Step 3: Get Your Embed Code

After saving, you'll receive the secret which we will need to verify that the request came from Sign Customiser in the next step, and HTML embed code that looks like this:

<div style="width: 100%; height: 100vh;">
  <script src="https://integrations.signcustomiser.com/sign-customiser-embed.js"></script>
  <sign-customiser-embed customiser-id="YOUR_CUSTOMISER_ID" integration-id="YOUR_INTEGRATION_ID" driver="custom"></sign-customiser-embed>
</div>

Place this code on the pages where you want customers to be able to customise signs.

Underneath the HTML embed code you should handle the "add to cart" step based on your own ecommerce platform:

<script>
window.addEventListener("message", (event) => {
  if (event.data.type === "sc:product:created") {
    // add the product to cart
  }
});
</script>

Part 2: Handling Product Creation

Your Product Creation Endpoint

When a customer creates a customised sign, we'll send a POST request to your configured URL with the following payload:

{ "product": { // Product details from Sign Customiser } }

You should verify that the request came from us by checking the signature.

Sign Customiser includes two important headers with each webhook:

x-webhook-timestamp: The Unix timestamp when the webhook was sent
x-webhook-signature: A SHA-256 HMAC signature of the payload

Implementation Steps

Step 1: Extract Headers and Payload

When your endpoint receives a request, extract the timestamp and signature from the headers, plus capture the raw request body:

const timestamp = req.headers["x-webhook-timestamp"];
const signature = req.headers["x-webhook-signature"];
const rawPayload = req.body.toString("utf8"); // Raw JSON string

Step 2: Verify Timestamp (Prevent Replay Attacks)

Check that the webhook timestamp is recent (within 5 minutes) to prevent replay attacks:

const currentTime = Math.floor(Date.now() / 1000);
const webhookTime = Number.parseInt(timestamp, 10);
const timeDiff = Math.abs(currentTime - webhookTime);
if (timeDiff > 300) { // 5 minutes in seconds 
  return false; // Reject old webhooks
}

Step 3: Create the Signature String

Combine the timestamp and raw payload to create the string that was signed:

const stringToSign = `${timestamp}.${rawPayload}`;

Step 4: Calculate Expected Signature

Using your secret (copied from the detail page), calculate what the signature should be:

const expectedSignature = crypto.createHmac("sha256", webhookSecret).update(stringToSign).digest("hex");

Step 5: Compare Signatures Securely

Use a constant-time comparison to prevent timing attacks:

const isValid = crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expectedSignature, "hex") );

Step 6: Create the product in your system and return the ID

Your endpoint must return a 200 status code and a JSON object with an "external_id" key

{ "external_id": "your-product-id-123" }

The external_id should be the unique identifier for the product in your system. We'll need this ID later when processing orders.

Part 3: Processing Orders

Generate API Keys

Before you can send orders to Sign Customiser, you'll need to generate API keys. View our API documentation for detailed instructions on generating and managing your API keys.

Send Orders to Sign Customiser

When an order is placed in your system that contains Sign Customiser products, POST the order details to:

Endpoint: https://web.signcustomiser.com/api/v2/orders

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Order Payload Structure

{
"integration_id": "YOUR_INTEGRATION_ID",
"external_id": "your-order-id-456",
"external_order_number": "ORDER-2024-001",
"currency": "USD",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+1234567890",
"address_1": "123 Main St",
"address_2": "Apt 4B",
"city": "New York",
"province": "NY",
"postcode": "10001",
"country": "US"
 },
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Main St",
"address_2": "Apt 4B",
"city": "New York",
"province": "NY",
"postcode": "10001",
"country": "US"
 },
"shipping_line": "Standard Shipping",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+1234567890"
 },
"products": [
{
"external_id": "your-product-id-123",
"quantity": 2,
"price": 2999
 }
]
}

Field Requirements

Required Fields

integration_id: Your Sign Customiser integration ID
external_id: Your internal order ID
external_order_number: Human-readable order number
products: Array of products in the order
products.*.external_id: Must match the ID you returned during product creation
products.*.quantity: Number of items (minimum 1)

Optional Fields

currency: Order currency (e.g., "USD", "EUR")
billing_address: Customer billing information
shipping_address: Delivery address
shipping_line: Shipping method description
customer: Customer details
products.*.price: Product price in cents (e.g., 2999 = $29.99)

Important Notes

Product External IDs: The external_id values in your order must exactly match the IDs you returned during the product creation process. This is how we link orders to the correct customised signs.
Prices: All price values should be in the smallest currency unit (cents for USD, pence for GBP, etc.)

LEGACY - WordPress and WooCommerce Integration

Generic Integration Guide

WooCommerce API Integration

Subscribe to Webhooks