Configure a webhook

By the end of this article you'll have a webhook endpoint configured in Carriyo. It will listen for the shipment events you care about and, optionally, filter by conditions such as destination geography.

🎬 Watch the full video walkthrough on Guidde

Before you start

• Endpoint URL: an HTTPS URL on your side that's ready to receive webhook callbacks (e.g. https://your-domain.com/carriyo-webhooks).
• A webhook handler that accepts POST with a JSON body and responds quickly with a 2xx. See Retry and idempotency for the cadence Carriyo retries with if your handler fails or is slow.

1. Open the webhooks settings

Go to Settings → Webhooks in the Carriyo Dashboard.

The page lists every webhook endpoint configured for the tenant.

2. Add a new webhook

Click the Add button to start a new webhook.

3. Name the webhook and set the endpoint URL

Give the webhook a descriptive name (for example, "Automatic shipment booked and label update") and enter the endpoint URL it should call. The URL must be HTTPS and publicly reachable.

4. Add triggers

Choose the events that should fire this webhook. In this example, add two triggers: Booked and Default Label is generated.

1. Click Add Record in the Webhook Triggers section.
2. Search for and select Booked, then click Add Trigger.
3. Click Add Record again.
4. Search for and select Default Label is generated, then click Add Trigger.

Repeat to add more triggers to the same webhook, each trigger is a separate event that will cause this webhook to fire.

5. Save the webhook

Click SAVE to persist the webhook configuration.

If you leave conditions empty, the webhook fires for every event that matches its triggers.

6. (Optional) Add conditions

Conditions narrow when the webhook fires. Each condition is a filter on a specific dimension of the entity (geography, delivery type, custom attributes, etc.). Multiple conditions on one webhook are AND-combined.

In this example, add a Dropoff by Geography condition, select United States of America, and uncheck Alaska.

6a. Start adding a condition

In the conditions area of the webhook form, click to add a new condition.

6b. Pick the condition type

Open the condition-type picker and choose Dropoff by Geography. This filter scopes the webhook to specific destination countries (or states / regions).

Other condition types are available, pickup country, delivery type, custom attributes, and so on. The Dashboard shows the full set; pick the one that matches what you want to filter on.

6c. Select the geography

Open the geography selector and pick the country or region you want to filter to, in this case, United States of America.

Uncheck any states or regions you do not want included. In this example, Alaska is excluded.

6d. Save the condition

Click Save to apply the condition to the webhook. It's now attached and will narrow when the webhook fires.

To add another condition (e.g. also filter by delivery type), repeat steps 6a–6d.

7. Save the webhook

Click SAVE at the top of the form to finalize the webhook. It's now live, the next event matching the triggers and conditions will be delivered to your endpoint.

Common pitfalls

• HTTPS only. HTTP endpoints are rejected. Use a real TLS certificate (Let's Encrypt is fine).
• Webhook count cap. A per-tenant limit on active webhook endpoints may apply. If you're at the cap, retire unused ones rather than asking for more.
• Slow handlers fail. Carriyo waits up to 30 seconds for a 2xx response. If your handler takes longer, Carriyo marks the delivery failed and retries, design for fast acknowledgment, background processing.
• No filter equals everything. A trigger with no conditions fires for every event of that type, across every merchant and every region in the tenant. Use conditions to scope.