Webhooks are used by many modern web services to communicate when events happen in the application. This means that as soon as an event occurs, Octopi can push data to your web server or licensed third-party software. This allows you to receive the data in near real-time, rather than polling the API in intervals (every X minutes).
Introduction to webhooks
Webhooks are "user-defined HTTP callbacks," which allow you to build or set up integrations, which are subscribed to specific supported events in Octopi. When one of those events is triggered, Octopi will send an HTTP Request, as a POST, to the URL you have configured for the webhook. This means the most current data is able to be sent at the time of the event.
Example
You can configure the reefer plugged in event to push data to a third-party application, which can help you visualize the JSON payload that Octopi pushes on your own custom dashboard.
To utilize webhooks you will need to build or license a web application that can accept the HTTP requests.
If you don't already have a web application, almost all server-side programming languages offer frameworks to assist you in building one.
Some option include:
- ASP.NET MVC for C#
- Servlets and Spark for Java
- Express for Node.js
- Django and Flask for Python
- Rails and Sinatra for Ruby
- Laravel, Symfony and YiiYii frameworks for PHP, or PHP can be used alone.
Note: The Octopi team cannot provide support or assistance for your own custom built application or licensed third-party software.
Before you begin
Enable the webhooks feature
The webhooks feature is not enabled by default. If you wish to utilize webhooks at your organization. Please contact the Octopi Customer Success Team to request that webhooks be enabled.
Enable permissions
Once the feature is enabled, the roles assigned to team members who will work with webhooks will require the following permissions to be enabled.
Permission |
Description |
| Webhooks: Read | Users can view the Webhooks page. |
| Webhooks: Write | Users can add new and edit existing webhooks. |
| Webhooks: Delete | Users can delete existing webhooks. |
If a required permission is not enabled for your role, and you cannot enable it yourself, contact an Admin user on your team and request that they enable the permission or reassign your user to role that has the required permissions enabled.
If your Admin cannot add or edit a permission, they must contact the Octopi Customer Success Team to request the required permissions.
Configuring a webhook
In the Main Menu, click Admin and select Webhooks. Then click the New button.
Enter the URL for the new webhook. You can choose which events will send you payloads. Click the toggle switch next to the events you require to enable them for the new webhook. Only subscribing to the specific events you plan on handling limits the number of HTTP requests to your server. You must subscribe to at least one event.
Supported Webhook Events
Event |
Event Trigger |
| Cargo Manifested |
Cargo is added to a manifest |
| Voyage Created | A new voyage is created. |
| Voyage Updated | Details for an existing voyage are updated. |
| Gate Selected | A terminal gate is selected |
| Cargo Gated In |
Cargo is gated in. |
| Cargo Gated Out | Cargo is gated out. |
| Cargo Loaded | Cargo is loaded onto a marine vessel. |
| Cargo Unloaded | Cargo is discharged from a marine vessel. |
| Reefer Plugged In | A reefer is plugged in. |
| Reefer Plugged Out | A reefer is unplugged. |
| Cargo Held | Cargo has its first hold placed on it. |
| Cargo Released | Cargo has its last hold lifted |
| Hold Applied | A hold is placed on cargo. |
| Hold Lifted | A hold is lifted from cargo. |
| Cargo Transferred In | Cargo is transferred in to the terminal. |
| Cargo Transferred Out | Cargo is transferred out from the terminal. |
| Train Departed | A train departs from the terminal. |
| Container Resealed | A container is resealed. |
| Rail Cargo Loaded | Cargo is loaded onto a rail car. |
| Rail Cargo Unloaded | Cargo is discharged from a rail car. |
| Container Stripped | Cargo is stripped from a container. |
| Truck Gated Out | A truck is gated out from the terminal. |
| Outbound EDI Failed | An outbound EDI message failed to send. |
| Berth Request Approved | A berth request was approved. |
| Cargo Overlanded | Cargo is overlanded during a discharge tally. |
| Cargo Overshipped | Cargo is overshipped during a loading tally. |
| Cargo Delivered | Cargo is delivered. |
| Cargo Stuffed | Cargo is stuffed into a container. |
| Cargo Yard Transfer | Cargo is relocated to a new yard slot. |
Generating a Shared Secret
To finish configuring a webhook, you will need to request a Shared Secret to verify that requests are coming from Octopi. Please contact the Octopi Customer Success Team to request your Shared Secret.
HTTP POST Payloads
When an event is triggered in Octopi, an HTTP POST request will be made to your configured URL. This request will include a JSON body with the payload, and a set of special HTTP headers you can use to identify the event.
HTTP Header |
Description |
X-Octopi-Event |
Name of the event that is triggered. |
X-Octopi-Delivery |
A GUID to identify the delivery. |
X-Octopi-Timestamp |
The time at which this delivery was triggered |
X-Octopi-Signature |
A signature you can use to verify that the request originated from Octopi. |
Every event will also include, in its JSON payload, an "event_type" field, which should mirror the value of the X-Octopi-Event header.
Developer Tools & Documentation
Please contact the Octopi Customer Success Team for access to the Developer Tools.