Webhooks

Webhooks Management Guide

Overview

Webhooks allow you to receive real-time notifications when specific events occur in the system. When a configured event happens, the system will send HTTP POST requests to the URLs you've specified in your webhook subscriptions.

Accessing Webhooks

Navigate to the Webhooks section from the main navigation menu under Settings. The Webhooks page displays a list of all webhooks configured for your company with search and filtering capabilities.

User Interface

The Webhooks page features a modern two-column layout:

• Left Column: Search results table showing all webhooks

• Right Column: Edit form for creating or editing webhooks

Search and Filtering

• Use the search box at the top to filter webhooks by event type

• Results are displayed in a paginated table

• Click on any webhook row to edit it in the right panel

Sorting

The webhook table supports sorting by:

• Event Type (alphabetical)

• Version

• Created date

Click on column headers to toggle between ascending and descending order.

Creating a New Webhook

1. Click the "Create New Webhook" button in the jumbotron (when no webhooks exist) or the "add a new one" link in the right panel

2. The edit form will appear in the right column

3. Fill in the required fields in the Webhook Information tab:

   1. Event: Select the event type that will trigger the webhook

      1. order_created: Triggered when a new order is created

      2. order_line_status_changed: Triggered when an order line's status changes

      3. order_fulfilled: Triggered when an order is fulfilled

      4. ex_factory_date_updated: Triggered when an order line's ex-factory date is updated

   2. Version: Select the webhook API version (currently version 1)

4. Add subscriptions in the Subscriptions tab:

   1. Click "Add a subscription" to add a new URL

   2. Enter the URL where you want to receive webhook notifications

   3. You can add multiple subscription URLs for the same webhook

5. Click "Save" to create the webhook

Editing a Webhook

1. Click on a webhook in the search results table

2. The edit form will load in the right column with two tabs:

   1. Webhook Information: Edit the event type and version

   2. Subscriptions: Manage subscription URLs

3. Make your changes

4. Click "Save" to update the webhook

Managing Subscriptions

Subscriptions are the URLs where webhook notifications will be sent. You can:

• Add a subscription: Click the "Add a subscription" button in the Subscriptions tab

• Remove a subscription: Use the delete button next to each subscription URL

• Multiple subscriptions: Add multiple URLs to receive the same webhook event at different endpoints

Subscription URL Requirements

• Must be a valid HTTP or HTTPS URL

• Should be accessible from the internet (for production webhooks)

• Should be able to receive POST requests

• Should return a 2xx status code to acknowledge receipt

Webhook Events

Order Created (order_created)

Triggered when a new order is created in the system. This webhook fires immediately after order creation and includes the complete order data.

Order Line Status Changed (order_line_status_changed)

Triggered whenever the status of an order line changes. This is useful for tracking order progress through different stages of fulfillment.

Order Fulfilled (order_fulfilled)

Triggered when an order is marked as fulfilled. This indicates that all items in the order have been completed and are ready for shipping or delivery.

Ex-Factory Date Updated (ex_factory_date_updated)

Triggered when an ex-factory date (XFD) history record is created for an order line. This webhook provides information about changes to the estimated or actual ex-factory dates.

The payload includes the order_line data and an ex_factory_date_history object with the following fields:

• id: The unique identifier of the history record

• ex_factory_date: The updated ex-factory date

• estimated_arrival_date: The updated estimated arrival date

• reason_code: The code indicating the reason for the update

• reason_description: A detailed description of the reason

• line_status: The status of the order line at the time of the update

• created_at: The timestamp when the update was recorded

• created_by: The user who performed the update

Webhook Payload

When a webhook event occurs, the system will send a POST request to each subscription URL with:

• Method: POST

• Content-Type: application/json

• Body: JSON object containing the event data

Outgoing webhooks (version 1) are built from order.to_liquid / order_line.to_liquid. There is no event name, timestamp, or company wrapper in the JSON body—only the structures below.

order_created

{
  "order": {
    "order_number": "...",
    "order_date": "MM-DD-YYYY HH:MM:SS",
    "ship_first_name": "...",
    "ship_last_name": "...",
    "ship_address_1": "...",
    "ship_address_2": "...",
    "ship_city": "...",
    "ship_state_region": "...",
    "ship_country": "...",
    "ship_postal_code": "...",
    "ship_phone_number": "...",
    "ship_method_carrier": "...",
    "ship_method_description": "...",
    "ship_method_code": "...",
    "ship_email": "...",
    "ship_company": "...",
    "note": "...",
    "custom_attributes": {},
    "purchase_order_number": "...",
    "sales_order_number": "...",
    "order_lines": [ /* each line as below */ ]
  }
}

order_line_status_changed

{
  "order_line": { /* single line payload */ }
}

order_fulfilled

{
  "order_lines": [ /* array of line payloads */ ]
}

ex_factory_date_updated

{
  "order_line": { /* single line payload */ },
  "ex_factory_date_history": {
    "id": 1,
    "ex_factory_date": "...",
    "estimated_arrival_date": "...",
    "reason_code": "...",
    "reason_description": "...",
    "line_status": "...",
    "created_at": "...",
    "created_by": "..."
  }
}

ex_factory_date_history is omitted if no history record is found.

Shared order_line shape

{
  "sku": "...",
  "product_description": "...",
  "quantity": 1,
  "price": "...",
  "status": "...",
  "ex_factory_date": "MM-DD-YYYY HH:MM:SS",
  "estimated_arrival_date": "MM-DD-YYYY HH:MM:SS",
  "recipe_token": "...",
  "custom_attributes": {},
  "purchase_order_number": "...",
  "sales_order_number": "...",
  "customer_requested_date": "MM-DD-YYYY HH:MM:SS",
  "invoice_number": "...",
  "ship_method_code": "...",
  "ship_method_description": "...",
  "recipe": {},
  "generated_artwork": [
    { "filename": "...", "url": "...", "image_src": "..." }
  ]
}

recipe is included only when a matching recipe exists; generated_artwork comes from production files with traveler images.

Best Practices

1. Use HTTPS URLs: Always use HTTPS for webhook subscriptions to ensure data security

2. Implement idempotency: Your webhook endpoint should handle duplicate notifications gracefully

3. Respond quickly: Return a 2xx status code quickly to acknowledge receipt, then process asynchronously if needed

4. Monitor failures: Set up monitoring for webhook delivery failures

5. Version your endpoints: Use webhook versioning to handle API changes gracefully

6. Test endpoints: Use a testing tool to verify your webhook endpoints are working before going live

Troubleshooting

Webhooks Not Being Received

• Verify the subscription URL is accessible from the internet

• Check that your endpoint returns a 2xx status code

• Review server logs for any errors

• Ensure the webhook is active and the event type matches the events occurring in the system

Duplicate Webhooks

• Implement idempotency checks in your webhook handler

• Use unique identifiers in the payload to detect duplicates

• Consider using a message queue to handle webhook processing

Webhook Delivery Failures

• Check your endpoint's availability and response times

• Verify SSL certificates are valid for HTTPS URLs

• Review firewall and security settings that might block incoming requests

• Check the system's webhook delivery logs for specific error messages

Permissions

Access to webhooks is controlled by the webhook_event_editor permission. Users with this permission can:

• View all webhooks for their company

• Create new webhooks

• Edit existing webhooks

• Delete webhooks

• Manage webhook subscriptions