> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/oms/webhooks.md).

# Webhooks

The events performed by OMS, such as the results of actions carried out in the OMS and the new states of the domain objects, are transferred by OMS to third-party software via webhooks.

When a particular event occurs, webhooks asynchronously notify users who have [subscribed](#subscribe) to that event via a URL. The webhooks under the roof of OMS are grouped under the four headings below:

* [Creating Packages and Status Updates](#creating-packages-and-status-updates)
* [Changing Shipment Status](#changing-shipment-status)
* [Creating Transfers and Status Updates](#creating-transfers-and-status-updates)
* [Creating and Updating Stock Locations](#creating-and-updating-stock-locations)

## <mark style="color:red;">Subscribe</mark>​ <a href="#subscribe" id="subscribe"></a>

To monitor the actions relating to a particular event, an OMS webhook object must be created containing information such as `target_url`, `event_type`, etc.

<table><thead><tr><th width="266.37109375">Parameter</th><th>Detail</th></tr></thead><tbody><tr><td><code>event_type</code></td><td>Event subject to notification</td></tr><tr><td><code>target_url</code></td><td>URL with the event information</td></tr><tr><td><code>retry_countdown_config</code></td><td>Can be defined for retry time (fixed-linear-exponential-random)</td></tr><tr><td><code>additional_headers</code></td><td>If additional header information is required for the requested service, this can be filled (can be null)</td></tr><tr><td><code>secret_key</code></td><td>can be used if an encrypted key is required for the request. (can be null)</td></tr></tbody></table>

```
curl -X POST \
> -H "Authorization: Token <secret login token>" \
> -H "Content-Type: application/json" \
> -d '{"event_type": "package-created", 
       "target_url": "http://example.com/", "secret_key": "secret",  }' \
> http://oms-app.com/whisperer/hooks/
```

## <mark style="color:red;">Unsubscribe</mark>​ <a href="#unsubscribe" id="unsubscribe"></a>

```
curl -X DELETE http://oms-app.com/whisperer/hooks/{webhook-id}/
> -H "Authorization: Token <secret login token>" \
```

## <mark style="color:red;">Creating Packages and Status Updates​</mark> <a href="#creating-packages-and-status-updates" id="creating-packages-and-status-updates"></a>

* `package.created` Triggered when a new package is created.
* Triggered when the `package.status.transitioned` status of a package is updated to `transitioned`.
* Triggered when the `package.status.packed` status of a package is updated to `packed`.
* Triggered when the `package.status.cancelled` status of a package is updated to `cancelled`.
* Triggered when the `package.status.shipped` status of a package is updated to `shipped`.
* Triggered when the `package.status.packed_for_refund` status of a package is updated to `packed_for_refund`.
* Triggered when the `awb_number` of a `package.shipment.awb_number` package is set.

## <mark style="color:red;">Changing Shipment Status​</mark> <a href="#changing-shipment-status" id="changing-shipment-status"></a>

* `shipment.created` Triggered when a new “shipment” is created for a package or a transfer is set to be made to another location.
* `shipment.status.updated` Triggered when the “shipment” or transfer status of a package is updated.
* `shipment.cancelled` Triggered when the “shipment” or inter-location transfer of a package is canceled.

## <mark style="color:red;">Creating Transfers and Status Updates​</mark> <a href="#creating-transfers-and-status-updates" id="creating-transfers-and-status-updates"></a>

* `transfer.status.created` Triggered when new transfers are created.
* Triggered when the `transfer.status.transitioned` status of a transfer is updated to `transitioned`.
* Triggered when the `transfer.status.in_transit` status of a transfer is updated to `in_transit`.
* Triggered when the `transfer.status.transferred` status of a transfer is updated to `transferred`.
* Triggered when the `transfer.status.cancelled` status of a transfer is updated to `cancelled`.
* Triggered when the `transfer.status.ready_to_shipment` status of a transfer is updated to `ready_to_shipment`.

## <mark style="color:red;">Creating and Updating Stock Locations​</mark> <a href="#creating-and-updating-stock-locations" id="creating-and-updating-stock-locations"></a>

* `stock_location.created` Triggered when a new stock location is created.
* `stock_location.updated` when a stock location is updated


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/oms/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
