Skip to main content
This guide explains what subscriptions are and shows you how to create them to receive real-time event notifications from Quivo. Instead of polling for status changes, subscriptions allow Quivo to push data to your server via an HTTP POST request whenever a specific event occurs.

​
What are subscriptions?

Subscriptions are webhook configurations that notify your server when specific events happen in the Quivo system. When you create a subscription, you specify:
  • Entity type: The type of resource you want to monitor (for example, orders or shipments)
  • Endpoint URL: The HTTPS endpoint on your server that receives the notification data
When an event occurs for the subscribed entity type, Quivo sends a POST request to your endpoint with event details. Your endpoint must return a 200 OK response to confirm receipt of the notification.
Important: Your webhook endpoint must return a 200 OK response to confirm receipt of the notification. If your endpoint does not return 200 OK, Quivo may retry the webhook or mark it as failed.

​
Prerequisites

Before you start, make sure you have:
  • Session token: A valid session token. See the Authentication guide to learn how to obtain one.
  • API key: Your static API key provided by Quivo.
  • Seller ID: Use the GET /sellers endpoint to find it.
  • Public URL: A secure HTTPS endpoint on your server capable of receiving JSON POST requests.
All API examples in this guide use ${BASE_URL} as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see Environments page.

​
Supported Entity Types

The following table lists the supported entity types and the events that trigger notifications:
EntityTriggers On
ORDERSOrder creation, status changes (for example, to PROCESSING).
SHIPMENTSShipment creation, tracking updates (for example, IN_TRANSIT, DELIVERED).
INBOUNDSInbound shipment status changes.
RETURNSWhen a return is created or received at the warehouse.
INVOICESInvoice creation and updates.

​
Create a subscription

Create a subscription when you want to start receiving real-time notifications about specific events. Use the POST /subscriptions endpoint to create a new subscription. You need to construct a JSON payload containing your sellerId, the entity type, and the endpoint configuration. The following example shows how to subscribe to SHIPMENTS updates:
Use this request to create a webhook subscription for a specific entity.
curl -X POST "${BASE_URL}/subscriptions" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": <YOUR_SELLER_ID>,
    "entity": "SHIPMENTS",
    "endpoint": {
      "type": "WEBHOOK",
      "url": "<YOUR_WEBHOOK_URL>"
    }
  }'

​
Request body fields

The request body must include the following fields:
  • sellerId (required): The unique integer ID for your merchant account.
  • entity (required): The entity type you want to subscribe to. Must be one of: ORDERS, SHIPMENTS, INBOUNDS, RETURNS, or INVOICES.
  • endpoint (required): An object containing:
    • type: Must be "WEBHOOK".
    • url: The HTTPS URL of your webhook endpoint that receives notifications.

​
Where to go next

Now that you can create subscriptions, continue with these guides:

Manage Subscriptions

Learn how to list and delete your existing subscriptions.

Webhook Responses

Configure and manage event subscriptions via the API.