Webhook Notifications

Webhook notifications provide a seamless way for systems to communicate in real time by automatically sending data updates when specific events occur. Instead of constantly polling an API for changes, webhooks push relevant information directly to your application, improving efficiency and responsiveness.

• Order Updates
  Receive notifications when a new order is placed, modified, or processed.
• Shipment Updates
  Get real-time updates when an order is shipped, including tracking details and estimated delivery times.
• Cancellation Requests
  Stay informed when an order cancellation request status changes.

Supported Event Types

Each message has an associate event type that you can use to properly route and parse incoming notifications.

Subscribing to Notifications

Each notification event type requires an individual subscription. You may choose to send all messages to a single endpoint or dedicate separate endpoints. For information on creating a new subscription, see Create a New Subscription.

Failed Messages

The Spreetail Notifications service expects a 200 OK status code to be returned by your receiving endpoint. Other HTTP status codes or connection timeouts will result in a failed message. We will automatically retry to send any failed message up to 10 times over a period of 2-3 hours.

Message Authentication

Offline Validation

Every message sent by Spreetail contain three authentication header fields: X-Message-Hash, X-Message-Signature, and X-Message-Id. These fields can be used to verify the authenticity of any message you have received.

• X-Message-Hash
  This value is a SHA256 hash representation of the body of the sent message.
• X-Message-Signature
  This value is the SHA256/Pkcs1 signed representation of the X-Message-Hash value.
• X-Message-Id
  The unique identifier for the received message.

Both values are transmitted as Base64 encoded strings.

Using this information, you can verify that a received message is authentic. Additionally, you will need our Notification Public Key value:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAj6TswDzczwCkBZcyfX5a\
siaqRwwmgAGC8yLq0WCrPp7OZDKTDRjYllQacKv9NdXJT4TnVGBOTl8Ug46IckQF
XbCgly/H3pluvaCeGAu9HS7YElIYo0otVwlcSARgI8rGYR01gPweq2ub4wEDZLg6
dg929Ry3X+Sj86K1cXQYyjkIiP4qtzuEOzcpCuJKXQ1p1ZxrkQub/7lDO6XFqe6n
zGZIx14Byu0XiyanVUvUV8YQ41ZG9iamc6Ybo1petjYAmoODUw7K5CH40ur+Qh1H
ODnENkG/bRQgm8uxAfqY/vcLpETRuQuuNSyif5rV7qrWh4dDmElLxMwJxXFNMerB
pQIDAQAB
-----END PUBLIC KEY-----

A usage example can be found in the Code Examples section:

Validation Via API Calls

You can also validate the message authenticity utilizing the Spreetail API. With the provided X-Message-Id header value or messageId body value, you call the Get a Notification Message endpoint to validate the signature value.

Firewall/Inbound IP Filtering

Calls from the Spreetail Webhook Notification system will come from one of these IP addresses:

• 52.202.204.5
• 44.218.126.62

You may need to add these IP addresses to your firewall to allow for inbound traffic.

Notification Message

Notification Messages will be sent to your subscribed endpoints as they occur. Each message has a standardized set of fields and HTTP headers.

Message Body

{
  "id": "5af2457f-fe28-4cef-8794-5e187f56280c",
  "eventType": "order.cancellationrequest.updated",
  "subscriptionId": "83ea8619-89b1-4c1d-a6dd-a43805b7ca4b",
  "timestamp": "2025-01-01T01:02:03.123+00:00",
  "data": { }
}

Message Headers