Advanced Webhooks

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

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.
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.

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