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

FieldDetails
idID of the object being sent over.
objectThe type of object being sent: order, item, product, etc.
event.uuidUUID of the event.
event.object_idID of the event's object being sent over.
event.object_typeID of the event's object type being sent over.
event.actionThe name of the event. This matches the list of subscribable events in the settings.
event.messageHuman readable message of event.
event.timestampWhen the event occured.
event.userWho triggered the event. ("<email>" | "Dreamship Staff" | "System")
dataThe 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",
                  	"carrier_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=23423423423423423423",
                  	"status": "transit"
                }
            ]
        }
    ]
}

Signature Verification

X-Dreamship-Signature on a webhook's headers can be used to verify that a webhook came from Dreamship. A signature segement is a SHA-256 hash of a UTF-8 encoded api key and the request body. If you have multiple api keys, X-Dreamship-Signature will be multiple segments seperated by commas.

import hmac
import hashlib

# Get your api key from https://app.dreamship.com/app/settings/api/
my_api_key = '**************************'

# If you have multiple api keys, signature will be multiple signature segements seperated by commas.
signature = request.headers.get('X-Dreamship-Signature')

calculated_signature = hmac.new(my_api_key.encode('utf-8'), request.body, hashlib.sha256).hexdigest()

segments = signature.split(',')

# Check to see if the signature for your api key is inside of the segment list
valid = calculated_signature in segments