# 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:

<table><thead><tr><th width="279">Event type</th><th>Description</th><th>Payload</th></tr></thead><tbody><tr><td><code>delivery_status_updated</code></td><td>The delivery status of a shipment has changed</td><td><a href="/pages/C2IZKaWwloghZhBO0my2#the-shipment-resource">Shipment object</a></td></tr><tr><td><code>shipment_status_updated</code></td><td>The status of a shipment has changed</td><td><a href="/pages/C2IZKaWwloghZhBO0my2#the-shipment-resource">Shipment object</a></td></tr><tr><td><code>restocking_shipment_status_updated</code></td><td>The delivery status of a restocking shipment has changed</td><td><a href="/pages/F31e2GDdQCxSHvmZrPj8">Restocking shipment object</a></td></tr><tr><td><code>return_status_updated</code></td><td>The delivery status of a return has changed</td><td><a href="/pages/sKth8PNBWDZTjkFpzvta">Return object</a></td></tr></tbody></table>

{% hint style="info" %}
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.
{% endhint %}

## 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:

{% tabs %}
{% tab title="Ruby" %}

```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
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hive.app/reference/api-reference/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.