Webhooks

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

Setup
Navigate to the API settings page.

Click manage subscriptions and select the webhook subscriptions you want updates for.
Set a valid webhook url that will return a 200 response. If a url fails too many times the webhook url will become inactive.
(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.

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

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

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