Sparkbox Webhook Documentation

HTTP POST payloads that are delivered to your webhook's configured URL endpoint contain several important properties.

HTTP Headers

Sparkbox webhooks contain special HTTP headers. Below are the headers used:

• Content-Type

  • Description: Specifies the media type of the resource. For webhook payloads, it should be set to application/json.
  • Example: Content-Type: application/json

• X-Event-Type

  • Description: The type of the workflow event that triggered the webhook. (This also appears in the payload body under event.type).
  • Example: X-Event-Type: model.submitted

• X-Hook-UUID

  • Description: The UUID of the webhook.
  • Example: X-Hook-UUID: 123e4567-e89b-12d3-a456-426614174001

• X-Attempt-Number

  • Description: The number of times the payload has been sent. Has a maximum of 5.
  • Example: X-Attempt-Number: 3

• X-Sparkbox-Signature

  • Description: HMAC signature of the payload.
  • Example: X-Sparkbox-Signature: sha256=5e011ee705920362b3c19e01fd84510fff715a612419d1b4912fa8bf894b6d85

HTTP Body

Sparkbox webhooks deliver payloads in JSON format. Below is an overview of the payload structure.

Payload Structure

1. Event Object

• id: A unique event ID.
• type: The workflow event that triggered the payload.
• timestamp: The timestamp indicating when the event occurred.
• api_version: The API version.

2. Data Object

• Additional data related to the event. (See Event Types below.)

Example:

{
  "event": {
    "id": "abcdefgh-ijkl-mnop-qrst-uvwxyz012345",
    "event_type": "model.submitted",
    "timestamp": "2023-11-16T12:30:45Z",
    "api_version": "v1"
  },
  "data": [
    // Event-specific data
  ]
}

Event Types

1. Event Type: model.submitted

• Description: Triggered when a department region-wave is submitted.
• Data Payload:
  • uuid: a unique ID for the recommendation in the department region-wave.
  • taken: taken status of the recommendation in the department region-wave.
  • status: workflow status of the recommendation in the department region-wave.
  • sku_id: the sku ID corresponding to the product for which the recommendation was generated.
  • division_desc: the description of the division corresponding to the product for which the recommendation was generated.
  • department_desc : the description of the department corresponding to the product for which the recommendation was generated.
  • sku_desc : the description of the product for which the recommendation was generated.
  • current_price : current price of the product for which the recommendation was generated.
  • opt_price : the recommended price.
  • units_to_md : number of units that will be marked down.
  • start_date : start date of the recommended price.
  • end_date : end date of the recommended price.
  • wave_type : type of wave

2. Event Type: model.approved

• Description: Triggered when a department region-wave is approved.
• Data Payload:
  • uuid: a unique ID for the recommendation in the department region-wave.
  • taken: taken status of the recommendation in the department region-wave.
  • status: workflow status of the recommendation in the department region-wave.
  • sku_id: the sku ID corresponding to the product for which the recommendation was generated.
  • division_desc: the description of the division corresponding to the product for which the recommendation was generated.
  • department_desc : the description of the department corresponding to the product for which the recommendation was generated.
  • sku_desc : the description of the product for which the recommendation was generated.
  • current_price : current price of the product for which the recommendation was generated.
  • opt_price : the recommended price.
  • units_to_md : number of units that will be marked down.
  • start_date : start date of the recommended price.
  • end_date : end date of the recommended price.
  • wave_type : type of wave

3. Event Type: model.retracted

• Description: Triggered when a department wave-region is retracted.
• Data Payload:
  • uuid: a unique ID for the recommendation in the department region-wave.
  • taken: taken status of the recommendation in the department region-wave.
  • status: workflow status of the recommendation in the department region-wave.
  • sku_id: the sku ID corresponding to the product for which the recommendation was generated.
  • division_desc: the description of the division corresponding to the product for which the recommendation was generated.
  • department_desc : the description of the department corresponding to the product for which the recommendation was generated.
  • sku_desc : the description of the product for which the recommendation was generated.
  • current_price : current price of the product for which the recommendation was generated.
  • opt_price : the recommended price.
  • units_to_md : number of units that will be marked down.
  • start_date : start date of the recommended price.
  • end_date : end date of the recommended price.
  • wave_type : type of wave

HTTPS

Using HTTPS is recommended for your webhook URL because it is more secure. Sparkbox webhooks support either HTTP or HTTPS. If you are using HTTPS, your SSL/TLS certificate must be validated. (Self-signed certificates are not supported.)

Validate payloads

Ensure your server only processes webhook payloads that were sent by Sparkbox by validating the signature before processing the payload further.

If one is provided, Sparkbox will use a secret token to create an HMAC signature sent as the value of the X-Sparkbox-Signature header.

To validate the payload, generate the signature yourself by creating a hash of the entire received payload (using the shared secret as a key) and compare that signature with the signature you receive from Sparkbox.