Hive Merchant API
  • Hive Merchant API
  • Quick Start
  • Changelog
  • Reference
    • API Reference
      • General
      • SKUs
      • Orders
      • Shipments
      • Warehouses
      • Restocking Shipments
      • Returns
      • Webhooks
Powered by GitBook
On this page
Export as PDF
  1. Reference
  2. API Reference

Webhooks

PreviousReturns

Last updated 5 months ago

Webhooks allow merchants to be notified of significant events. For example, when the delivery status of a shipment changes. When an webhook-supporting event happens, an HTTP POST request will be sent to the URL of your choice.

To set up webhooks, ask your account manager. You need to provide the URL which handles the webhooks.

The following table shows the supported events and the type of payload which will be sent in the request:

Event type
Description
Payload

delivery_status_updated

The delivery status of a shipment has changed

shipment_status_updated

The status of a shipment has changed

restocking_shipment_status_updated

The delivery status of a restocking shipment has changed

return_status_updated

The delivery status of a return has changed

The provided webhooks urls should be idempotent, we cannot guarantee the order of the calls neither the retries attempts for the same call.

Security

Hive signs all webhook requests to prevent malicious actors from sending invalid requests. Requests without the x-hive-signature HTTP request should be ignored. If the header is present, it should match the hex-encoded HMAC-SHA256 digest of the request body, with your API token as the key.

Here's an example of how one would calculate the HMAC-SHA256 digest:

def request_valid?(req) # req is an instance of Rack::Request
  return false if !req.post?
  request_sig = req.get_header("x-hive-signature")
  expected_sig = OpenSSL::HMAC.hexdigest("sha256", ENV["API_TOKEN"], req.body)
  Rack::Utils.secure_compare(request_sig, expected_sig)
end
Restocking shipment object
Return object
Shipment object
Shipment object