Working With Webhooks
You can configure webhook endpoints to receive notifications about events related to your shipments and return requests in Carriyo.
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 will wait up to 30 seconds for a 200 response. If no response is received within this timeframe, or if Carriyo receives a response other than 200, it will retry the webhook three additional times within the next 5 minutes.
If the webhook is still unsuccessful after these retries, no further automatic attempts will be made. However, you have the option to manually trigger the webhook once automatic retries are 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.