Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur on your orders or returns. Instead of polling the API for updates, configure a webhook URL to receive automatic notifications.

Configuration

Configure your webhook URL in the Zinc dashboard under Settings. You can also generate a webhook secret for signature verification.

Webhook Secret

Your webhook secret is used to verify that incoming webhook requests are from Zinc. The secret format is:

zn_whsec_XXXXXXXXXXXXXXXXXXXXXXXX

Keep your webhook secret secure. If compromised, rotate it immediately in the dashboard. Rotating the secret invalidates the previous one.

Events

Order events

Event	Description
`order.started`	Order has been created and queued for processing
`order.placed`	Order was successfully placed with the retailer
`order.failed`	Order failed after all retry attempts were exhausted
`order.tracking_received`	Tracking number(s) were received from the retailer
`order.shipped`	The first package on the order started moving through the carrier network. Fires once per order
`order.estimated_delivery_updated`	The retailer revised the order’s estimated delivery date (Amazon Business orders)
`order.available_for_pickup`	A package is waiting at a carrier facility for the recipient to collect. Fires per package
`order.delivered`	All packages on the order have been delivered
`order.cancelled`	Retailer cancelled the order after placement (your wallet is refunded automatically)

Return events

Return events carry an additional return_id field alongside order_id so you can route by return without parsing the data object. The status field on these events reflects the return-request status (not the order status).

Event	Description
`return.created`	A return was filed against one of your orders
`return.label_uploaded`	A printable mail-back label is ready for the return
`return.approved`	A return was approved — typically accompanied by a merchant RMA / label URL
`return.denied`	A return was denied (e.g. outside the return window)
`return.credited`	A return was resolved by crediting the customer’s wallet rather than working a merchant RMA

Wallet events

Wallet events aren’t about an order, so they use a smaller payload with no order_id, return_id, or top-level status. See Wallet event payloads.

Event	Description
`wallet.auto_topup.succeeded`	An automatic wallet top-up charged your card
`wallet.auto_topup.failed`	An automatic wallet top-up couldn’t charge your card
`wallet.auto_topup.disabled`	Auto top-up was switched off, either after 3 failed attempts in a row or straight away if the card was permanently declined. Sent right after the `failed` event that triggered it

Payload Structure

All webhook payloads follow this structure:

{
  "event": "order.placed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {}
}

Payload Fields

Field	Type	Description
`event`	string	The event type (e.g., `order.started`, `order.placed`, `return.approved`)
`order_id`	string	The UUID of the order
`return_id`	string \| null	The UUID of the return request. Only populated on `return.*` events; `null` for order events.
`status`	string	Current status of the subject. For order events this is the order status; for return events it’s the return-request status.
`timestamp`	string (ISO 8601)	When the event occurred
`data`	object	Additional event-specific data

Event-Specific Data

order.placed includes price components:

{
  "event": "order.placed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "price_components": {
      "subtotal": 1999,
      "shipping": 499,
      "tax": 150,
      "total": 2648
    }
  }
}

order.failed includes error information:

{
  "event": "order.failed",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_failed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "error_type": "product_not_found",
    "error": "The product is no longer available"
  }
}

Tracking events (order.tracking_received, order.shipped, order.available_for_pickup, order.delivered) all carry data.tracking_numbers. Each entry has:

Field	Description
`carrier`	The shipping carrier
`tracking_number`	The carrier’s tracking number
`zinc_tracking_number`	Zinc’s own tracking number for the shipment (`ZPY…YQ`). It never changes, even if the carrier’s tracking number is corrected later. May be `null`
`order_item_ids`	The order items in this package, when known

On these events the top-level status is the order’s status, which stays order_placed once the order is placed. Shipment progress is reported by the event itself and by each tracking number’s status. order.tracking_received includes the tracking numbers we just received:

{
  "event": "order.tracking_received",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "tracking_numbers": [
      {
        "carrier": "UPS",
        "tracking_number": "1Z999AA10123456784",
        "zinc_tracking_number": "ZPY1A2B3C4D5YQ",
        "order_item_ids": ["8f14e45f-ceea-467f-a8f4-1d2a3b4c5d6e"]
      }
    ]
  }
}

order.shipped fires once per order, when the first package starts moving through the carrier network. It lists every tracking number on the order so far:

{
  "event": "order.shipped",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-16T08:15:00Z",
  "data": {
    "tracking_numbers": [
      {
        "carrier": "UPS",
        "tracking_number": "1Z999AA10123456784",
        "zinc_tracking_number": "ZPY1A2B3C4D5YQ",
        "order_item_ids": ["8f14e45f-ceea-467f-a8f4-1d2a3b4c5d6e"]
      }
    ]
  }
}

order.estimated_delivery_updated fires when the retailer revises a delivery estimate you’ve already been given, whether it slips or moves earlier. The first estimate on an order doesn’t fire it. Today it’s sent for Amazon Business orders only. estimated_delivery and previous_estimated_delivery are passed through as the retailer reports them: either a date (2026-01-19) or an ISO 8601 timestamp (2026-01-19T03:00:00Z):

{
  "event": "order.estimated_delivery_updated",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-16T09:00:00Z",
  "data": {
    "estimated_delivery": "2026-01-19",
    "previous_estimated_delivery": "2026-01-18"
  }
}

order.available_for_pickup fires for one package each time it moves into available_for_pickup. A multi-package order can send several. available_at is when the package first became available in its current pickup run, and location is the carrier facility, when the carrier reports it. It isn’t sent when nothing on the order can still reach the shopper (for example, a cancelled order):

{
  "event": "order.available_for_pickup",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-17T15:05:00Z",
  "data": {
    "tracking_numbers": [
      {
        "carrier": "USPS",
        "tracking_number": "9400111899223197428490",
        "zinc_tracking_number": "ZPY6F7G8H9J0YQ",
        "available_at": "2026-01-17T14:52:00",
        "location": {
          "city": "Louisville",
          "state": "KY",
          "zip": "40209",
          "country": "US"
        },
        "message": "Available for Pickup",
        "order_item_ids": ["8f14e45f-ceea-467f-a8f4-1d2a3b4c5d6e"]
      }
    ]
  }
}

order.delivered fires when every package on the order has been delivered. Each tracking number adds delivered_at and delivery_proof_url (the carrier’s proof-of-delivery photo, or null). delivered_at may be missing when the retailer, rather than the carrier, reported the delivery:

{
  "event": "order.delivered",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "tracking_numbers": [
      {
        "carrier": "UPS",
        "tracking_number": "1Z999AA10123456784",
        "zinc_tracking_number": "ZPY1A2B3C4D5YQ",
        "delivered_at": "2026-01-15T13:42:00",
        "delivery_proof_url": "https://carrier.example.com/pod/abc.jpg",
        "order_item_ids": ["8f14e45f-ceea-467f-a8f4-1d2a3b4c5d6e"]
      }
    ]
  }
}

order.cancelled fires when the retailer cancels the order after placement. The order’s wallet hold is refunded at the same time:

{
  "event": "order.cancelled",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled_by_retailer",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "reason": "cancelled_by_retailer",
    "merchant_order_id": "112-1234567-1234567",
    "refund_amount": 2648
  }
}

return.created fires when a customer files a return against one of your orders. The data object echoes the return reason, free-text notes, and the line items being returned:

{
  "event": "return.created",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "a1b2c3d4-e29b-41d4-a716-446655440099",
  "status": "open",
  "timestamp": "2026-01-20T10:00:00Z",
  "data": {
    "reason": "damaged",
    "notes": "Box arrived crushed",
    "items": [
      { "order_item_id": "item-abc", "quantity": 1 }
    ]
  }
}

return.label_uploaded fires when a printable mail-back label is attached to the return, which can happen before, at the same time as, or after approval. It fires again if the label is replaced. label_url is a signed link you can fetch straight from the payload. It stops working at label_url_expires_at (7 days), and it’s null if signing failed. In that case, fetch the label from GET /returns/{return_id}. kind is label_pdf or package_label:

{
  "event": "return.label_uploaded",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "a1b2c3d4-e29b-41d4-a716-446655440099",
  "status": "open",
  "timestamp": "2026-01-20T12:00:00Z",
  "data": {
    "attachment_id": "5d41402a-bc4b-4a76-b971-9d911017c592",
    "kind": "label_pdf",
    "label_url": "https://storage.example.com/evidence/abc.pdf?signature=...",
    "label_url_expires_at": "2026-01-27T12:00:00",
    "return_tracking_number": "1Z999AA10123456785",
    "return_carrier": "ups",
    "external_label_url": null
  }
}

return.approved fires when the return is approved. Where applicable, the data object carries the merchant-issued return id and a printable label URL so you can hand them to the customer:

{
  "event": "return.approved",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "a1b2c3d4-e29b-41d4-a716-446655440099",
  "status": "approved",
  "timestamp": "2026-01-20T14:30:00Z",
  "data": {
    "reason": "damaged",
    "resolution_notes": "RMA filed with Amazon",
    "merchant_return_id": "RMA-1234",
    "external_label_url": "https://carrier.example.com/labels/abc.pdf"
  }
}

return.denied fires when the return is denied (e.g. outside the retailer’s return window). merchant_return_id and external_label_url are null on denied returns:

{
  "event": "return.denied",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "a1b2c3d4-e29b-41d4-a716-446655440099",
  "status": "denied",
  "timestamp": "2026-01-20T14:30:00Z",
  "data": {
    "reason": "no_longer_needed",
    "resolution_notes": "Outside return window",
    "merchant_return_id": null,
    "external_label_url": null
  }
}

return.credited fires when the return is resolved by crediting the customer’s wallet rather than working a merchant RMA. There’s no carrier label or merchant return id in this flow:

{
  "event": "return.credited",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "a1b2c3d4-e29b-41d4-a716-446655440099",
  "status": "credited",
  "timestamp": "2026-01-20T14:30:00Z",
  "data": {
    "reason": "damaged",
    "resolution_notes": "Item unrecoverable, no RMA needed",
    "merchant_return_id": null,
    "external_label_url": null
  }
}

Wallet event payloads

Wallet events report the top-up amount in cents and its outcome. error is included on failed and disabled:

{
  "event": "wallet.auto_topup.failed",
  "timestamp": "2026-01-21T09:00:00",
  "data": {
    "amount_cents": 50000,
    "status": "failed",
    "error": "Your card was declined."
  }
}

Event	`data.status`
`wallet.auto_topup.succeeded`	`success`
`wallet.auto_topup.failed`	`failed`
`wallet.auto_topup.disabled`	`disabled`

Security

Webhook requests include headers for verification:

Header	Description
`Content-Type`	Always `application/json`
`X-Webhook-Signature`	HMAC-SHA256 signature of the payload
`X-Webhook-Event`	The event type

Verifying Signatures

To verify a webhook is from Zinc, compute the HMAC-SHA256 signature of the raw request body using your webhook secret and compare it to the X-Webhook-Signature header. Python Example:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler
@app.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Webhook-Signature")

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

    data = json.loads(payload)
    # Process the webhook event

Node.js Example:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  // Process the webhook event
});

Always verify webhook signatures before processing the payload to ensure the request originated from Zinc.

Best Practices

Respond quickly - Return a 2xx status code as soon as possible. Process the webhook asynchronously if needed.
Handle duplicates - Webhooks may occasionally be delivered more than once. Deduplicate on event together with order_id (or return_id for return events). Wallet events have neither, so use event and timestamp.
Verify signatures - Always validate the X-Webhook-Signature header before trusting the payload.
Use HTTPS - Configure an HTTPS endpoint to ensure webhook data is encrypted in transit.
Log events - Keep records of received webhooks for debugging and auditing.

Getting Started

Agent Sandbox

Device Approval

Search (Beta)

Orders

Bulk Orders

Managed Accounts

Returns

Product Data

Retailers

Agent

Wallet

Usage

Webhooks

Configuration

Webhook Secret

Events

Order events

Return events

Wallet events

Payload Structure

Payload Fields

Event-Specific Data

Wallet event payloads

Security

Verifying Signatures

Best Practices

​Configuration

​Webhook Secret

​Events

​Order events

​Return events

​Wallet events

​Payload Structure

​Payload Fields

​Event-Specific Data

​Wallet event payloads

​Security

​Verifying Signatures

​Best Practices

Configuration

Webhook Secret

Events

Order events

Return events

Wallet events

Payload Structure

Payload Fields

Event-Specific Data

Wallet event payloads

Security

Verifying Signatures

Best Practices