Postbacks are automated notifications sent from GelatoConnect to external systems whenever an order status changes. They're essential for keeping Print Service Providers (PSPs) and customers informed about their orders in real-time, without requiring manual updates.

Postbacks enable you to:

Notify customers automatically when their order status changes (e.g. received, shipped, delivered).
Alert your team about orders requiring attention (failed orders).
Update your inventory management systems when orders are completed.
Track order progress throughout your fulfillment workflow.

These notifications can be delivered via webhooks (URL) or email, depending on your integration needs.

Prerequisites for setting up postbacks

Before creating postbacks, ensure you have:

Customers who will receive notifications are configured in the customers section of GelatoConnect.
URL endpoints are ready to receive webhook data (if using the URL delivery method).
A basic understanding of templates and triggers.
Familiarity with the order status flow in GelatoConnect.

Step-by-step guide to setting up postbacks

1. Create a postback template

Templates define the structure and content of your postback notifications. You can create them in two ways:

Option A: Through the templates section

Navigate to Workflow > Order Intake > Templates
Click Add Template
Select the template type:
- Trigger: Webhook - For sending JSON or XML data to external systems
- Trigger: Email - For sending email notifications
Choose the appropriate format (JSON or XML)

Option B: Through the customer profile

Go to your customer's profile
Navigate to the Triggers tab and click Add Trigger
You'll be able to create the template directly within the trigger setup

For detailed guidance on creating templates, see Creating Templates for Order Intake.

2. Configure a trigger

Triggers determine when postbacks are sent and where they're delivered:

Name your trigger descriptively (e.g., "Order Shipped Notification")
Select the event that will activate the trigger:
- Order received
- Order failed
- Order canceled
- Order returned
- Order produced
- Order delivered
- Order shipped
- Order in transit
Choose your delivery method:
- URL (webhook): Sends data to a specified endpoint
- Email: Sends notifications via email
For URL delivery, configure:
- The destination URL where notifications will be sent
- Set the method to POST (recommended)
- You can choose JSON or XML as the data format
- Enable "Retry on Failure" for reliability
For Email delivery, configure the recipient email address.

3. Add a template

Your template transforms GelatoConnect's internal data into a format that's useful for your and your customers' systems.

If a template is already created, you can select it during trigger configuration, otherwise, you'll need to create a new one.

Give your template a clear name (e.g., "OrderShippedNotification")
Use the sample payloads provided for your selected event type
Map the input data fields to your desired output format using the Template Mapper

Example Template for "Order Shipped" Event:

{
  "event": "Order Shipped",
  "orderId": "{{ orderId }}",
  "orderReferenceId": "{{ orderReferenceId }}",
  "timestamp": "{{ created }}",
  "status": "{{ fulfillmentStatus }}",
  "trackingInfo": {
    {% for item in items %}
      {% for fulfillment in item.fulfillments %}
        "trackingCode": "{{ fulfillment.trackingCode }}",
        "trackingUrl": "{{ fulfillment.trackingUrl }}",
        "carrier": "{{ fulfillment.carrierName }}"
      {% endfor %}
    {% endfor %}
  }
}

Use the "Render" button to preview how your output will appear
Test the template to ensure it generates the expected output

For more template examples, see Template Mapper Examples.

4. Test and activate

Before going live with your postback, send some tests to check it's all working as expected. You can subsequently change the statuses of your trigger and template to active.

After completing these steps, the system will send a postback to the designated URL or email address with the relevant order information every time the specified order event occurs.

Advanced postback techniques

Using Lookups in Your Templates

Lookups are useful for mapping internal values to customer-friendly formats:

{% set carrier = lookups({"shipmentMethodUid": fulfillment.carrierUid}, strict=False, default="") %}
"carrier": "{{ carrier }}"

This converts internal GelatoConnect codes to more meaningful values for your customers. Learn more in How to Setup Lookups.

Event-specific data fields

Different events provide different data fields. Here are the key fields available for common events:

Order Shipped/Delivered: tracking codes, carrier information, delivery dates
Order Failed/Canceled: error reasons, timestamps
Order Received: order details, item information

For a complete understanding of these fields, see Introduction to Template Mappers in GelatoConnect.

Troubleshooting postbacks

If your postbacks aren't working as expected:

Verify that the destination URL is correct and accessible
Check the template syntax for errors
Confirm the trigger is properly configured for the correct event
Look for mismatched data types or missing fields
Test the template with sample data before activating

For email postbacks specifically:

Verify your SMTP server details are correct (if configured)
Check that the sender's email address is properly formatted
Ensure your SMTP server allows the connection from GelatoConnect
Check if the authentication details (username/password) are correct

For more comprehensive advice on troubleshooting, refer to the "Troubleshooting" section in Creating Templates for Order Intake.

Configuring your email server for postbacks

As a Print Service Provider, you can configure GelatoConnect to send email postbacks using your own email server. This means recipients will see emails coming from your domain rather than from GelatoConnect, maintaining your brand consistency.

To configure your email server settings:

Navigate to the Workflow section in the left sidebar
Find the Configuration section and select Work Settings
Locate the Outgoing email server settings section
Enter the following details:
- Sender Email Address: The email address that will appear in the "From" field
- Sender Name: The name that will appear alongside the email address
- SMTP Server: Your email server address (e.g., smtp.yourcompany.com)
- SMTP Port: The port your email server uses (commonly 587 or 465)
- SMTP Username: The username for authenticating with your SMTP server
- SMTP Password: The password for your SMTP server
- Use TLS: Enable this if your SMTP server requires TLS encryption (recommended)
Save your configuration

Once configured, all email postbacks will be sent through your email server, ensuring consistent branding and improving deliverability to your customers.