As of July 2021, there are two types of webhook services that Dreamship offers. The original Basic Webhooks and the new Advanced Webhooks. Dreamship plans on deprecating Basic Webhooks at some point in 2022, and recommends that all new API users utilize the Advanced Webhooks.

Advanced Webhooks

Setup

  1. Add a valid url in the Dreamship API settings page to be your global webhook url endpoint.
    A valid url can also be added into the webhook_url field when creating an order. If a webhook url is set on order creation, that url will take priority over a global url for updates on that order.

  2. Enable Advanced Webhooks.

Event Subscriptions
Advanced webhooks allow you to control what types of Events you want to subscribe to. You can view the list of subscribable events by clicking Manage Subscriptions on the API settings page.

Data
The data will be sent as a POST call to your webook url. The data will be formatted as JSON and sent over in the following format

Field

Details

id

ID of the object being sent over.

object

The type of object being sent: order, item, product, etc.

event.uuid

UUID of the event.

event.object_id

ID of the event's object being sent over.

event.object_type

ID of the event's object type being sent over.

event.action

The name of the event. This matches the list of subscribable events in the settings.

event.message

Human readable message of event.

event.timestamp

When the event occured.

event.user

Who triggered the event. ("<email>" | "Dreamship Staff" | "System")

data

The latest data of the object. This data matches the same format as the GET requests.

{
  "id": 3346950,
  "object": "order",
  "event": {
    "uuid": "85fd0f85-6e93-4bba-a0cb-3cd0755ede24",
    "object_id": 3346950,
    "object_type": "order",
    "action": "order-created",
    "message": "Order created through App",
    "timestamp": "2021-07-06T18:10:30.103721Z",
    "user": "[email protected]"
  },
  "data": {...}
}

Response
Dreamship must receive back a 200 status response on a webhook call. The response must be sent back to Dreamship within 30 seconds or the call will timeout and be considered a failed delivery.

Retries
If Dreamship fails to deliver the webhook, it will retry delivery a total of 10 times over the course of 72 hours. Continued webhook delivery failures may result in Dreamship temporarily disabling webhooks for your account. You will be notified over email when we disable the endpoint. The webhook endpoint can be turned back on via the Dreamship app once the correct response logic has been implemented in your system.

Basic Webhooks

📘

Dreamship recommends all new API users to implement the Advanced Webhooks. Support for Basic Webhooks will be shut off in 2022.

Dreamship offers basic webhook updates on the Order object. Every time the status of the order changes, you can receive webhooks from Dreamship in two ways. One way is to set a global webhook url at https://dreamship.com/app/settings/. Another option is to include a valid url on the webhook_url field when creating an order. If a webhook url is set on order creation, that url will take priority over a global url for updates on that order.

Response
Dreamship must receive back a 200 status response on a webhook call. The response must be sent back to Dreamship within 30 seconds or the call will timeout and be considered a failed delivery.

Retries
If Dreamship fails to deliver the webhook, it will retry delivery a total of 10 times over the course of 72 hours. Continued webhook delivery failures may result in Dreamship temporarily disabling webhooks for your account. You will be notified over email when we disable the endpoint. The webhook endpoint can be turned back on via the Dreamship app once the correct response logic has been implemented in your system.

Data
The order data will be sent as a POST call to your webook url. The data will be formatted as JSON and match the response object given in /orders/{id}

Basic Example:

{
    "id": 9944382,
    "status": "fulfilled",
    "reference_id": null,
    "cost": "18.00",
    "test_order": false,
    "line_items": [
        {
            "id": 972329,
            "quantity": 1,
            "item_variant": 2342,
            "product_variant": 2341711772,
            "print_areas": [
                {
                    "key": "11oz",
                    "url": "https://image.com/",
                    "url_error": null
                }
            ]
        },
        {
            "id": 9722330,
            "quantity": 1,
            "item_variant": 2342,
            "product_variant": 2171123773,
            "print_areas": [
                {
                    "key": "11oz",
                    "url": "https://image.com/",
                    "url_error": null
                }
            ]
        }
    ],
    "address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": null,
        "phone": null,
        "street1": "xxxxxxxxx",
        "street2": "",
        "city": "SAN DIEGO",
        "state": "CA",
        "country": "US",
        "zip": "92126",
        "verified_delivery": true,
        "force_verified_delivery": null
    },
    "fulfillments": [
        {
            "id": 10432322,
            "line_items": [
                {
                    "id": 9437229,
                    "quantity": 1,
                    "item_variant": 2342,
                    "product_variant": 2341711772,
                    "print_areas": [
                        {
                            "key": "11oz",
                            "url": "https://image.com/",
                            "url_error": null
                        }
                    ]
                },
                {
                    "id": 97230,
                    "quantity": 1,
                    "item_variant": 2342,
                    "product_variant": 2171123773,
                    "print_areas": [
                        {
                            "key": "11oz",
                            "url": "https://image.com/",
                            "url_error": null
                        }
                    ]
                }
            ],
            "trackings": [
                {
                    "tracking_number": "23423423423423423423",
                    "carrier": "USPS"
                }
            ]
        }
    ]
}