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
Click on "Integrations" from the home screen
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 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.
You will also be able to copy the secret which we will need to verify that the request came from Sign Customiser in the next step.
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 sentx-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 IDexternal_id: Your internal order IDexternal_order_number: Human-readable order numberproducts: Array of products in the orderproducts.*.external_id: Must match the ID you returned during product creationproducts.*.quantity: Number of items (minimum 1)
Optional Fields
currency: Order currency (e.g., "USD", "EUR")billing_address: Customer billing informationshipping_address: Delivery addressshipping_line: Shipping method descriptioncustomer: Customer detailsproducts.*.price: Product price in cents (e.g., 2999 = $29.99)
Important Notes
Product External IDs: The
external_idvalues 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.)