Introduction

Webhooks provide a mechanism for real-time communication between systems by allowing one system to send data to another system as events occur. This document outlines how to configure and use webhooks within our system.


Event Payload Structure

When an event occurs to which a webhook is subscribed, Rose Rocket sends a POST request to your configured URL with a JSON payload containing details about the event. The common structure of the payload is:


{
  "id": "string",
  "type": "string",
  "refId": "string",
  "ownerId": "string",
  "orgId": "string",
  "json": {
    // Event-specific data
  },
  "createdAt": "string",
  "objectKey": "string"
}

Event Payload Attributes

ParameterTypeRequiredDescription
idStringYesUnique identifier of the webhook event.
typeStringYesType of the webhook event.
refIdStringYesReference identifier associated with the webhook event.
ownerIdStringYesUnique identifier of the user or account who triggers the webhook event.
createdAtStringYesTimestamp indicating when the webhook event occurred.

It follows UTC date-time.
orgIdStringYesA JSON object containing additional data specific to the event.
jsonA JSON object containing additional data specific to the event.
objectKeyStringYesKey identifying the object related to the webhook event.

Available Events

The events available for webhooks can vary depending on the modules or features you have enabled in your system. At present, the default event that is available is the Order Status Change, which is triggered when the status of an order changes.
All events share common attributes such as id, type, refId, ownerId, orgId, createdAt, objectKey. These attributes remain consistent across all events.
Each event includes event-specific details stored within a JSON object.
The contents of the JSON may vary depending on the specific event that triggered the webhook.

Webhooks Configuration

You can configure a webhook using two methods using UI and API.


Via the User Interface (UI).

To configure a webhook using the UI, follow these steps:

  1. Navigate to your webhooks settings page by going to Profile > Settings> API Settings> Webhooks.
  2. Create a new webhook destination.
  3. Provide a name for the destination, specify the URL where the webhook payload should be sent and select the event that triggers the webhook.
  4. Save the destination.

Via the API.

To configure a webhook using the API, follow these steps:

  1. Send a POST request to the following endpoint
    POST https://network.roserocket.com/api/v2/platformModel/objects
    
  2. Include a JSON body with the following structure:
    Example JSON
    {
      "objectKey": "webhookDestination",
      "json": {
        "name": "Test to XYZ Freight ",
        "url": "https://hooks.XYZfreightcorporation.com/hooks/catch/15958505/3x03dpa/",
        "subscriptions": [
          {
            "objectKey": "webhookSubscription",
            "eventName": "Order Status Changed"
          }
        ]
      }
    }
    

Configuration Attributes


ParameterTypeRequiredDescription
objectKeyStringYesKey identifying the object type, for example webhookDestination.
nameStringYesType a name for the webhook destination.
urlStringYesURL where Rose Rocket will send webhook notifications.
subscriptions[Array](## Subscription)YesAn array of objects representing subscriptions to specific events.

Subscription

ParametersTypeRequiredDescription
objectKeyStringYesKey identifying the object related to the webhook event, for example webhookSubscription.
eventNameStringYesName of the event the webhook should be triggered for. For example, Order Status Changed.

Error Handling

Rose Rocket will retry sending the webhook notification up to 3 times with a 30-second delay if it receives a failure code from your server.

Retry Mechanism:

  • Upon occurrence of an event, the payload is sent to all subscribed webhooks.
  • If a webhook recipient responds with a failure code, the system retries up to 3 times with a 30-second delay between attempts.
  • Webhooks provide at-least-once delivery guarantees. However, if all retries fail, delivery is not guaranteed.

Error Codes


CodeMessages
400 Bad RequestInvalid request parameter being sent.
401 UnauthorizedThe user is not authorized to access the resource, or the authentication token has expired.
404 Not FoundNo object found with the provided ID.
500 Internal Server ErrorThe request cannot be processed.

Viewing Webhook History

You can view webhook history for up to 7 days from the Webhooks section in the API settings, which includes both successful and failed webhooks. In the case of failed webhooks, you can view the error responses returned from the webhook recipient.

To view webhook history, follow the steps below:

  1. Navigate to Profile > Settings> API settings> Webhooks.
  2. In the Webhook Receipts section, you can use the filters to view by Event Type, Event ID, Retries, Status, and Response.

Limitations

  • The webhook functionality is currently limited in terms of supported events and custom event definitions.
  • Additionally, you can only specify a Webhook URL when registering subscriptions. The functionality to generate or input a ClientID and Client Secret for Basic Auth is not yet available.

Troubleshooting

If you encounter issues with Webhooks integration, refer to the Webhook Receipts section for detailed information on failed attempts. Following are the common reasons for failure:

  • Incorrect URL:Double check that the URL you provided for your webhook endpoint is accurate.
  • Incorrect paths: Verify that the paths specified for your webhook are correct.
  • Webhook destination server not running: Ensure that the server intended to receive webhook payloads is up and running.