Rarely ResourcesResources

Webhooks

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

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.

products.created
Sent when a merchant product is created.
products.updated
Sent when a merchant product changes.
products.submitted
Sent when a product enters review.
products.approved
Sent when a product is approved.
products.rejected
Sent when a product is rejected.
products.hidden
Sent when a product is hidden from selling surfaces.
collections.created
Sent when a merchant collection is created.
collections.updated
Sent when a merchant collection changes.
collections.submitted
Sent when a collection enters review.
collections.approved
Sent when a collection is approved.
collections.rejected
Sent when a collection is rejected.
media.created
Sent when a media asset is created.
media.submitted
Sent when a media asset enters review.
media.approved
Sent when a media asset is approved.
media.rejected
Sent when a media asset is rejected.
landing_pages.created
Sent when a landing page is created.
landing_pages.updated
Sent when a landing page changes.
landing_pages.submitted
Sent when a landing page enters review.
landing_pages.approved
Sent when a landing page is approved.
landing_pages.rejected
Sent when a landing page is rejected.
social_videos.created
Sent when a social video is created.
social_videos.updated
Sent when a social video changes.
social_videos.submitted
Sent when a social video enters review.
social_videos.approved
Sent when a social video is approved.
social_videos.rejected
Sent when a social video is rejected.
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.
inventory.low_stock
Sent when available stock crosses a merchant low-stock threshold.
inventory.out_of_stock
Sent when available stock reaches zero.
fulfillments.created
Sent when a merchant fulfillment record is created.
fulfillments.updated
Sent when a fulfillment changes status, items, or tracking.
fulfillments.tracking_updated
Sent when fulfillment tracking details are added or changed.
fulfillments.canceled
Sent when a fulfillment is canceled.
returns.created
Sent when a return request is created.
returns.updated
Sent when a return request changes.
returns.approved
Sent when a return is approved.
returns.rejected
Sent when a return is rejected.
returns.received
Sent when returned goods are received.
refunds.created
Sent when a refund is created.
refunds.updated
Sent when a refund changes.
customers.created
Sent when a customer record is created.
customers.updated
Sent when a customer record changes.
customer_segments.updated
Sent when customer segment rules or memberships change.

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 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"
  }
}

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

Search docs

Search guides, endpoints, scopes, and parameters.