Webhooks

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 object
shipment_status_updated	The status of a shipment has changed	Shipment object
restocking_shipment_status_updated	The delivery status of a restocking shipment has changed	Restocking shipment object
return_status_updated	The delivery status of a return has changed	Return object

The provided webhook URLs should be idempotent. We cannot guarantee the order of the calls neither the retries attempts for the same call.

What this means in practice, is that you should check the timestamp of the object in the payload. Ignore payloads with a timestamp older than the last update you saved. Only process the webhook if the updated timestamp is newer than the one you have on file.

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:

Ruby

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