Basic webhooks have been deprecated and will be shut off in 2023. If you are using basic webhooks you must switch to the Advanced Webhooks on the API settings page.

Navigate to the API settings page.

  1. Click manage subscriptions and select the webhook subscriptions you want updates for.
  2. Set a valid webhook url that will return a 200 response. If a url fails too many times the webhook url will become inactive.
  3. (Optional) Set the webhook_url field when creating an order and this url will take priority over the global webhook url.

Catalog Inventory Updates
Subscribe to the item-variant-availability-updated webhook subscription.

It is recommended you setup a new Dreamship account for testing. Create orders with test_order=True that you will not be charged for. If you have order webhooks subscriptions selected, you will get webhooks for each stage in the lifecycle.

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.

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.

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

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": {...}

Signature Verification

X-Dreamship-Signature on a webhook's headers can be used to verify that a webhook came from Dreamship. A signature segment 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