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

Parameter	Type	Required	Description
`id`	String	Yes	Unique identifier of the webhook event.
`type`	String	Yes	Type of the webhook event.
`refId`	String	Yes	Reference identifier associated with the webhook event.
`ownerId`	String	Yes	Unique identifier of the user or account who triggers the webhook event.
`createdAt`	String	Yes	Timestamp indicating when the webhook event occurred. It follows UTC date-time.
`orgId`	String	Yes	A JSON object containing additional data specific to the event.
`json`			A JSON object containing additional data specific to the event.
`objectKey`	String	Yes	Key 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:

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

Via the API.

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

Send a POST request to the following endpoint

POST https://network.roserocket.com/api/v2/platformModel/objects

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

Parameter	Type	Required	Description
`objectKey`	String	Yes	Key identifying the object type, for example webhookDestination.
`name`	String	Yes	Type a name for the webhook destination.
`url`	String	Yes	URL where Rose Rocket will send webhook notifications.
`subscriptions`	[Array](## Subscription)	Yes	An array of objects representing subscriptions to specific events.

Subscription

Parameters	Type	Required	Description
`objectKey`	String	Yes	Key identifying the object related to the webhook event, for example webhookSubscription.
`eventName`	String	Yes	Name 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

Code	Messages
`400 Bad Request`	Invalid request parameter being sent.
`401 Unauthorized`	The user is not authorized to access the resource, or the authentication token has expired.
`404 Not Found`	No object found with the provided ID.
`500 Internal Server Error`	The 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:

Navigate to Profile > Settings> API settings> Webhooks.
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.