Setup Webhooks
You can configure webhook endpoints to be notified about events that happen to your shipments and return requests in Carriyo.
You must register a webhook endpoint to tell Carriyo where to send events. You can register up to 10 webhook endpoints with Carriyo.
The easiest way to register a webhook is via the Carriyo Dashboard. To register your webhook endpoint, you must choose the object type "Shipment" or "Return", and provide the publicly accessible HTTPS URL to your webhook endpoint, and select the events you want to receive in your endpoint.
The URL format to register a webhook endpoint is:
https://<your-website>/<your-webhook-endpoint>How does it work?
Carriyo will send JSON data to your webhook endpoint via POST. We will always send you the full object regardless of the event, so that you can choose what information you need to process the event on your side.
You must ensure that your webhook endpoint can process what information it needs and ignore unknown fields so that your webhooks don't fail when new fields are added to the Carriyo model. You can check what fields you will receive in the webhook payload by clicking on 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.
When Carriyo invokes your webhook endpoint, it will wait 30 seconds for a 200 response. If no response is received within 30 seconds or if Carriyo receives any other response code (other than 200), then Carriyo will retry the webhook endpoint for the same event three additional times within the next 5 minutes. If the webhook is unsuccessful even after three addition attempts, then no further attempts will be made.
If a webhook fails even after the third reattempt, then Carriyo will make no further automatic reattempts. Please Note: You still have the option to manually trigger a webhook after all automatic reattempts are exhausted.
Add a Webhook Endpoint via Dashboard
Use the following steps to add a webhook via the Carriyo Dashboard.
Step 1. Add New Webhook
- Login as a Carriyo admin to perform this action
- Navigate to Integrations > Webhooks
- Click the add button
Step 2. Configure Your Webhook
- Enter a Name for your webhook endpoint
- Choose the Webhook type - Shipment or Return Request
- Add your webhook endpoint’s URL
- Add any HTTP headers your endpoint expects
- Add triggers (events) you want to receive
- Add any conditions you wish to match
Add a Webhook Endpoint via API
You can also manage your webhook endpoints via the Carriyo API. Please refer to this link for more details
Manage webhook endpoints
You can update or delete existing webhook endpoints in the Dashboard’s Webhooks settings page. You also have the option of disabling a webhook endpoint temporarily. Alternatively, you can manage webhook endpoints programmatically.