Working With Webhooks

You can configure webhook endpoints to receive notifications about events related to your shipments and return requests in Carriyo.

• The Shipment Object
• The Return Request Object

To enable webhooks, you must register a webhook endpoint, which tells Carriyo where to send the events. You can register up to 10 webhook endpoints with Carriyo.

The easiest way to register a webhook is via the Carriyo Dashboard. When registering your webhook endpoint, choose the object type (either "Shipment" or "Return"), provide the publicly accessible HTTPS URL for the webhook endpoint, and select the events you want to receive.

The URL format to register a webhook endpoint should be as follows:

https://<your-domain>/<your-webhook-endpoint>

How Does It Work?

Carriyo sends JSON data to your webhook endpoint via POST. We will always send the full object regardless of the event, allowing you to process the event according to your needs.

To avoid issues when new fields are added to Carriyo models, ensure your webhook endpoint can process necessary information and ignore unknown fields. You can check which fields will be sent in the webhook payload by referring to the links below:

• For Shipment webhooks, Carriyo will always send the full Shipment Object for all shipment events.
• For Return Request webhooks, Carriyo will always send the full Return Request Object for all return request events.

Webhook Retry Logic

When Carriyo invokes your webhook endpoint, it waits up to 30 seconds for a 200 response. If no response is received within this timeframe or if Carriyo receives a non-200 response, it will retry the webhook three additional times using an exponential delay model.

Standard Retry Delays

The retry attempts and their corresponding delays are as follows:

Extended Retry Option

Carriyo also offers an extended retry feature. However, enabling this option requires careful consideration, as extended retries may lead to out-of-sequence events. If newer events are consumed while older, failed events are retried later, the event sequence could be disrupted. Therefore, it is recommended to enable extended retries only if your webhook endpoint can handle out-of-sequence events without issues.

The extended retry attempts and their delays are as follows:

Manual Retrigger Option

If all automatic retries (both standard and extended) are unsuccessful, no further automatic attempts will be made. However, you can still manually trigger the webhook after all automatic retries have been exhausted.

Add a Webhook Endpoint via the Dashboard

Follow these steps to add a webhook via the Carriyo Dashboard:

Step 1: Add a New Webhook

• Log in as a Carriyo admin.
• Navigate to Integrations > Webhooks .
• Click the Add button.

Step 2: Configure Your Webhook

• Enter a name for your webhook endpoint.
• Select the webhook type (Shipment or Return Request).
• Provide the URL for your webhook endpoint.
• Add any necessary HTTP headers your endpoint expects.
• Select the triggers (events) you want to receive.
• Add any conditions you wish to match.

You can also manage your webhook endpoints programmatically via the Carriyo API. Please refer to the API documentation for more details.

Manage Webhook Endpoints

You can update or delete existing webhook endpoints from the Webhooks settings page in the Dashboard. Additionally, you have the option to temporarily disable a webhook endpoint. Webhook endpoints can also be managed programmatically via the Carriyo API.