API Documentation

Everything you need to integrate RateShip into your application.

Webhooks

Receive real-time notifications when labels are purchased and when tracking status changes. Register a webhook endpoint URL and RateShip will POST events to it as they happen.

Event Types

Event	Description
label.purchased	A shipping label was purchased through RateShip
tracking.updated	Tracking status changed (in transit, out for delivery, etc.)
tracking.delivered	Package was delivered

Register an Endpoint

POST/api/v1/webhooks

Register a URL to receive webhook events. You can register up to 5 endpoints per environment. The response includes a secret that you should save immediately. It will not be shown again.

Request Body

Field	Type	Description
url	string	HTTPS URL to receive events
events	string[]	Array of event types to subscribe to

import { RateShip } from "rateship";

const rateship = new RateShip({ apiKey: "rs_dev_your_key_here" });

const endpoint = await rateship.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: ["label.purchased", "tracking.updated", "tracking.delivered"],
});

// Save endpoint.secret for signature verification

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "url": "https://your-app.com/webhooks",
    "events": ["label.purchased", "tracking.updated", "tracking.delivered"],
    "secret": "e4f5a6b7c8d9..."
  }
}

Event Payload

Every webhook delivery is a POST request with this JSON body:

{
  "id": "delivery-uuid",
  "event": "label.purchased",
  "created_at": "2026-03-15T12:00:00.000Z",
  "environment": "prod",
  "data": {
    "provider": "shippo",
    "carrier": "USPS",
    "service": "Ground Advantage",
    "tracking_number": "9400111899223...",
    "label_url": "https://cdn.goshippo.com/...",
    "price_cents": 965,
    "status": null,
    "status_detail": null
  }
}

For tracking events, the status field contains one of: in_transit, out_for_delivery, delivered, returned, failure, or unknown.

Delivery Headers

Header	Description
X-RateShip-Signature	HMAC-SHA256 signature of the request body, prefixed with `sha256=`
X-RateShip-Event	The event type (e.g. label.purchased)

Verifying Signatures

Every delivery is signed with your endpoint secret using HMAC-SHA256. Verify the signature against the raw request body to confirm the event came from RateShip.

const crypto = require("crypto");

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

// In your webhook handler:
const signature = req.headers["x-rateship-signature"];
const isValid = verifyWebhook(req.rawBody, signature, YOUR_WEBHOOK_SECRET);

Retries

If your endpoint returns a non-2xx status code or times out (10 second limit), RateShip will retry up to 3 times with a 5-minute interval between attempts. After 3 failed attempts, the delivery is marked as failed. You can manually retry failed deliveries from your dashboard.

Managing Endpoints

Method	Path	Description
GET	/api/v1/webhooks	List your endpoints
POST	/api/v1/webhooks	Register a new endpoint
PATCH	/api/v1/webhooks/:id	Toggle active/inactive
DELETE	/api/v1/webhooks/:id	Delete an endpoint