NAV Navbar
ruby python php java javascript

Webhooks

Use webhooks to be notified about events that happen in your Rose Rocket instance.

Webhooks lets you register a URL that we will notify anytime an event happens in your account. When the event occurs—for example, when an order is made for a customer, Rose Rocket creates an Event object. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Rose Rocket then sends the Event object to any URLs in your account’s webhooks settings via an HTTP POST request.

Configuring

Webhooks are configured in the webhooks settings section of the Settings. Clicking Add endpoint reveals a form to add a new URL for receiving webhooks.

You can enter any URL you’d like to have events sent to, but this should be a dedicated page on your server, coded per the instructions below. The mode determines whether test events or live events are sent to this URL; if you want to send both live and test events to the same URL, you need to create two separate settings. You may add as many URLs as you like, and basic access authentication is supported.

You can also choose to be notified of all event types, or only specific ones.

Receiving Webhooks

require "json"

# Using Sinatra
post "/my/webhook/url" do
  # Retrieve the request's body and parse it as JSON
  event_json = JSON.parse(request.body.read)

  # Do something with event_json

  status 200
end
import json
from django.http import HttpResponse

# Using Django
def my_webhook_view(request):
  # Retrieve the request's body and parse it as JSON
  event_json = json.loads(request.body)

  # Do something with event_json

  return HttpResponse(status=200)
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event_json = json_decode($input);

// Do something with $event_json

http_response_code(200); // PHP 5.4 or greater
// Using Spark framework (http://sparkjava.com)
public Object handle(Request request, Response response) {
  // Retrieve the request's body and parse it as JSON
  Event eventJson = APIResource.GSON.fromJson(request.body(), Event.class);

  // Do something with eventJson

  response.status(200);
  return "";
}
// Using Express
app.post("/my/webhook/url", function(request, response) {
  // Retrieve the request's body and parse it as JSON
  var event_json = JSON.parse(request.body);

  // Do something with event_json

  response.send(200);
});

Creating a webhoook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Rose Rocket that you did not receive the webhook. This does mean that a URL redirection or a “Not Modified” response will be treated as a failure.

If a webhook is not successfully received for any reason, Rose Rocket will not try to send the webhook, though you can use the API to reconcile your data with any missed events.

When viewing a specific event information through the Dashboard, you can check how many times we’ve attempted to send an event to an endpoint by clicking on that endpoint URL in the Webhook details section. This will show you the latest response we received from your endpoint, along with a list of all attempted webhooks and the respective HTTP status codes we received.

Best Practices

Before going live, test that your webhook is working properly. You can do so by sending dummy test events from the webhooks settings pane. Understand that as these are fake, test events, they will not map to real customers, invoices, charges, or other objects in your account.

If your webhook script performs complex logic, or makes network calls, it’s possible the script would timeout before Rose Rocket sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from Rose Rocket.

Types of events

Order Created

Event Name: order.created

{
    "event": "order.created",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is created.

Order Updated

Event Name: order.updated

{
    "event": "order.updated",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is updated.

Order Deleted

Event Name: order.deleted

{
    "event": "order.deleted",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is deleted.

Order Status Updated

Event Name: order.status_updated

{
    "event": "order.status_updated",
    "previous_status": "booked",
    "current_status": "dispatched",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order status changed.

Order Dispatched

Event Name: order.dispatched

{
    "event": "order.dispatched",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is dispatched.

Order Dispatched

Event Name: order.dispatched

{
    "event": "order.dispatched",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is dispatched.

Order Delivered

Event Name: order.delivered

{
    "event": "order.delivered",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order is delivered.

Order In Transit

Event Name: order.in_transit

{
    "event": "order.delivered",
    "order_id": "172dfbff-ebd9-4c9c-868c-cb79ef7775ed",
    "timestamp": "2018-01-01T00:00:00Z"
}

Occurs whenever an order’s status changes to in-transit.

Leg Created

Event Name: leg.created

{
    "event": "leg.created",
    "leg_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a leg is created.

Leg Deleted

Event Name: leg.deleted

{
    "event": "leg.deleted",
    "leg_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a leg is deleted.

Leg Dispatched

Event Name: leg.dispatched

{
    "event": "leg.dispatched",
    "leg_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a leg is dispatched.

Leg Loaded

Event Name: leg.loaded

{
    "event": "leg.loaded",
    "leg_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a leg is loaded.

Leg Unloaded

Event Name: leg.unloaded

{
    "event": "leg.unloaded",
    "leg_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a leg is unloaded.

Manifest Completed

Event Name: manifest.completed

{
    "event": "manifest.completed",
    "manifest_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a manifest completed.

Manifest Assigned

Event Name: manifest.assigned

{
    "event": "manifest.assigned",
    "manifest_id": "dba74129-806a-4bec-b7d2-81a8e0e1ad35",
    "timestamp": "2018-06-08T13:51:14.649392Z"
}

Occurs whenever a manifest is assigned.