Developer Docs

Webhooks

Subscribe to outbound merchant events for orders, inventory, and fulfillments, verify signatures, and understand retry and replay behavior.

Overview

Webhooks are the push layer for warehouse integrations.

Rarely delivers outbound JSON events to merchant-managed HTTPS endpoints. Warehouses should treat webhooks as a near-real-time signal and use the polling APIs for reconciliation and replay-safe backfill. For merchants with multiple warehouses, each endpoint can optionally be restricted to specific fulfillment locations.

orders.created

Sent when a merchant order is first created and ready for downstream intake.

orders.updated

Sent when a merchant order changes in a warehouse-relevant way.

orders.canceled

Sent when a merchant order transitions into canceled state.

inventory.updated

Sent when available quantity changes for a merchant-owned variant/location row.

fulfillments.created

Sent when a merchant fulfillment record is created.

fulfillments.updated

Sent when a fulfillment changes status, items, or tracking.

Signatures

Verify every webhook using the timestamped HMAC signature.

Every delivery includes timestamp and signature headers. Construct the signed payload as timestamp + '.' + raw request body, then compare your computed SHA-256 HMAC with the v1 signature value.

Headers

X-Rarely-Webhook-Id: evt_123
X-Rarely-Webhook-Event: orders.created
X-Rarely-Webhook-Timestamp: 1773648000
X-Rarely-Signature: t=1773648000,v1=HEX_HMAC_SHA256

Payloads

Payloads use a stable envelope with a typed event name and merchant-scoped data.

Every delivery includes the event id, event type, API version, merchant id, and a data object containing the event payload for that resource. When an endpoint is scoped to specific fulfillment locations, mixed-location orders are delivered as an order shell plus only the in-scope line items and fulfillments. Unassigned items stay hidden until a fulfillment location is assigned.

Envelope

{
  "id": "0a7a92a2-c463-4f5a-8dc0-3e9a52210384",
  "type": "orders.created",
  "created_at": "2026-03-17T17:45:02.000Z",
  "api_version": "2026-03-17",
  "merchant_id": "7a8f7c98-2724-4a74-bbbd-97f1f9af0bcb",
  "data": {
    "id": "723e7e7c-b4a4-4860-8fe4-e5969d699c32",
    "order_number": "R-1048",
    "merchant_status": "pending"
  }
}

Retries

Failed deliveries retry automatically and can be replayed from the merchant portal.

Non-2xx responses and transport failures retry on an increasing backoff. After the final retry, the delivery moves to dead-letter status. Merchants can replay individual deliveries from the Webhooks activity tab.

Retry schedule

Attempt 1: immediate
Attempt 2: +1 minute
Attempt 3: +5 minutes
Attempt 4: +15 minutes
Attempt 5: +1 hour
Attempt 6: +6 hours
Then: dead_letter

Webhooks

Webhooks are the push layer for warehouse integrations.

Verify every webhook using the timestamped HMAC signature.

Payloads use a stable envelope with a typed event name and merchant-scoped data.

Failed deliveries retry automatically and can be replayed from the merchant portal.

Search developer docs