Webhooks

Receive real-time notifications about events in your system

What are Webhooks?

Webhooks are HTTP callbacks that allow you to receive real-time notifications when specific events occur in your Connect2Print system.

Benefits of Webhooks:

How Webhooks Work

1
Register: You create a webhook in the Connect2Print admin panel and specify your endpoint URL
2
Event occurs: An event happens in the system (e.g., an order is created)
3
HTTP POST: Connect2Print sends an HTTP POST request to your endpoint with event data
4
Validate: Your server validates the webhook signature
5
Process: Your server processes the event data
6
Respond: Your server responds with status 200 to acknowledge receipt

Available Events

Connect2Print sends webhooks for the following events:

Order Events

Receive notifications about order changes:

  • order.created - A new order has been created
  • order.updated - An order has been updated
  • order.completed - An order has been completed
  • order.cancelled - An order has been cancelled
  • order.shipped - An order has been shipped

Invoice Events

  • invoice.created - A new invoice has been created
  • invoice.sent - An invoice has been sent
  • invoice.paid - An invoice has been paid

Quote Events

  • quote.created - A new quote has been created
  • quote.accepted - A quote has been accepted
  • quote.rejected - A quote has been rejected

Production Events

  • production.job.created - A new production job has been created
  • production.job.completed - A production job is complete

Other Events

  • customer.created - A new customer has been created
  • shipment.delivered - A shipment has been delivered
  • stock.low - Stock level is low

Creating Webhooks

Create and configure webhooks from the admin panel:

  1. Log in to the Connect2Print admin panel
  2. Navigate to Settings → Webhooks
  3. Click "Create New Webhook"
  4. Configure webhook:
    • URL: Your endpoint URL (HTTPS required)
    • Events: Select which events to receive
    • Secret: Generated automatically for signature validation
    • Active: Enable/disable the webhook
  5. Click "Save" and copy your webhook secret

Store the webhook secret securely - it's used to validate webhook signatures.

Webhook Payloads

All webhooks send data in the following format:

Payload Structure

Payload Fields:

Example: order.created Event

{
  "id": "wh_1a2b3c4d5e6f",
  "event": "order.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "order": {
      "id": 123,
      "order_number": "ORD-2024-001",
      "status": "pending",
      "total": 499.00,
      "customer": {
        "id": 456,
        "email": "customer@example.com"
      }
    }
  }
}

Signature Validation

All webhooks include an X-Webhook-Signature header that you MUST validate to ensure the request comes from Connect2Print.

How to Validate the Signature

  1. Get the signature header: X-Webhook-Signature
  2. Get the raw request body (JSON string)
  3. Calculate HMAC-SHA256 hash of the body using your webhook secret
  4. Compare the calculated hash with the signature header

Validation Examples

// PHP
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$body = file_get_contents('php://input');
$secret = 'your_webhook_secret';

$calculated = hash_hmac('sha256', $body, $secret);

if (!hash_equals($signature, $calculated)) {
    http_response_code(401);
    die('Invalid signature');
}

// Signature is valid, process the webhook
$data = json_decode($body, true);
// Node.js
const crypto = require('crypto');

function validateWebhook(body, signature, secret) {
  const calculated = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(calculated)
  );
}
# Python
import hmac
import hashlib

def validate_webhook(body, signature, secret):
    calculated = hmac.new(
        secret.encode(),
        body.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, calculated)

Handling Webhooks

Best practices for handling webhooks:

Respond quickly with 200

Respond with HTTP 200 status immediately. Process event data asynchronously in the background.

Always validate signature

Never trust the data without validating the webhook signature first.

Handle duplicates

The same event may be sent multiple times. Use the event id to deduplicate.

No guaranteed order

Webhooks are not necessarily sent in chronological order. Use timestamp to sort.

Implement timeout

Your endpoint must respond within 10 seconds, or it will be considered a failure.

Log webhook data

Log incoming webhooks for debugging and audit trail.

Retries and Error Handling

If your endpoint fails or doesn't respond, Connect2Print automatically retries:

Retry Schedule:

You can view webhook delivery status and retry history in the admin panel.

Testing Webhooks

Test your webhooks before production setup:

Use Test Endpoint

Use a tool like webhook.site to inspect webhook payloads.

Manual Test Event

Use the "Send Test Event" feature in the admin panel to send a sample payload.

Local Testing

Use ngrok to expose your local server for webhook deliveries.

Test via API

Send a test webhook programmatically:

POST /api/v1/webhooks/{id}/test
Authorization: Bearer YOUR_API_KEY

// Example response
{
  "success": true,
  "message": "Test webhook sent"
}

Next Steps

Now that you understand webhooks, explore related topics:

Authentication

Learn how webhook secrets are used for signature validation

Authentication →

Error Handling

Handle webhook failures and retries effectively

Error Handling →

API Reference

See all available webhook events and their payloads

API Reference →

Code Examples

Copy-and-paste webhook handlers in different languages

Code Examples →