Webhooks
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.
Updated about 1 month ago