Webhooks v2

Webhooks v2 is an enhanced webhook system that delivers real-time event notifications to your endpoint. Unlike the legacy webhook connection which uses separate URLs per event category, Webhooks v2 sends all events to a single URL with granular control over which event types you receive.

Each webhook is signed with an HMAC signature for payload verification, and you can configure custom headers for additional authentication with your endpoint.

Key Differences from Legacy Webhooks:

Single URL: One endpoint receives all event types
Granular Events: Subscribe to specific events instead of broad categories (e.g. shipment_scheduled instead of all shipment events)
HMAC Signatures: Every webhook is signed for payload verification
Custom Headers: Add authentication headers to each request
Paid Transactions Only: Shipment events only fire for shipments associated with completed, non-declined transactions

Setup

Navigate to Settings > Connections > Add New Connection > Other
Select Webhook 2.0
Configure the following:
- Name - Give your webhook connection a name
- Webhook URL - Your HTTPS endpoint that will receive all events
- Event Types - Select which events to subscribe to
- Secret - Used to generate HMAC signatures for payload verification
- Custom Headers (optional) - Add custom headers sent with each request (e.g. API keys)
- Campaign Filter (optional) - Limit events to specific campaigns
Use the Test button to send a sample webhook to your endpoint
Activate the connection and save

Webhook Payload Format

Every webhook follows this structure:

{
  "webhook_type": "shipment",
  "webhook_event": "shipment_scheduled",
  "webhook_event_id": 12345,
  "webhook_event_date": "2026-03-22 14:30:00",
  "webhook_event_subtype": null,
  "webhook_data": {
    ...
  }
}

Field	Description
`webhook_type`	The object type: `shipment`, `order_offer`, `order`, `transaction`, `customer`, `item`, `offer`, `merchant`, `campaign`
`webhook_event`	The specific event name (e.g. `shipment_scheduled`)
`webhook_event_id`	Unique event ID. Use this for idempotency to avoid processing duplicates
`webhook_event_date`	Timestamp when the event occurred
`webhook_event_subtype`	Additional context for certain events (may be null)
`webhook_data`	The full object data at the time of the event

Signature Verification

Each webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, signed with your configured secret. Verify this on your server to ensure the webhook is authentic.

signature = HMAC-SHA256(secret, request_body)

Events

Shipment Events

Shipment events only fire for shipments associated with a completed, non-declined transaction. Shipments for pending or future transactions will not generate webhook events until the transaction is paid.

shipment_scheduled — A shipment is ready to be fulfilled. This event fires in the following scenarios:

A new shipment is created and its transaction has already been paid
A pending shipment's transaction completes successfully (status changes from pending to active)
The scheduled fulfillment date is changed on an active shipment (reschedule)
A previously skipped shipment is unskipped and its transaction is paid

This is the primary event for fulfillment integrations — when you receive shipment_scheduled, the shipment is paid for and ready to prepare.

shipment_fulfilled — The shipment has been successfully posted to a fulfillment provider and received a fulfillment ID.

shipment_shipped — A tracking number has been added and the shipment is marked as shipped.

shipment_cancelled — The shipment has been cancelled. This can happen manually, from a subscription cancellation, or as part of a swap/quantity change.

shipment_error — The shipment encountered an error. This fires when a fulfillment post fails and returns an error, or when a shipment is manually marked as error.

shipment_skipped — The shipment has been skipped for this billing cycle.

shipment_rma — A Return Merchandise Authorization has been issued for the shipment.

shipment_address_updated — The shipping address associated with the shipment has changed. This fires when:

The shipping address ID on the shipment is changed to a different address
A customer edits the details of an address that is linked to pending shipments

shipment_item_updated — The items on the shipment have been modified. This fires when items are added, removed, or swapped on the shipment.

Order Offer (Subscription) Events

order_offer_activated — The subscription is now in an active state. This is a unified event that fires whenever a subscription becomes active, regardless of how it got there:

Initial activation when the first transaction completes successfully
Reactivation of a previously cancelled subscription
Unpausing a paused subscription
Recurring transaction completes on a subscription

Use this event to grant access, resume fulfillment, or sync the active status to external systems.

order_offer_cancelled — The subscription has been cancelled.

order_offer_paused — The subscription has been paused. Billing and fulfillment are temporarily suspended until the subscription is unpaused.

order_offer_expired — The subscription has expired based on its configured expiration rules.

order_offer_swapped — The offer on the subscription has been swapped to a different offer. The subscription remains active but is now associated with a new product/offer.

order_offer_quantity_changed — The quantity on the subscription has been changed.

order_offer_frequency_changed — The billing frequency (charge timeframe) on the subscription has been changed (e.g. monthly to quarterly).

Order Events

Event	Description
`order_created`	A new order has been created.
`order_ordered`	The order has been placed (first successful transaction).
`order_updated`	The order has been modified. This is a pre-existing event that fires on any order edit.
`order_abandoned`	The order was abandoned without completing a purchase.

Transaction Events

Event	Description
`transaction_completed`	A transaction has been processed (approved or declined).
`transaction_skipped`	A scheduled transaction was skipped.
`transaction_unskipped`	A previously skipped transaction was reset.

Customer Events

Event	Description
`customer_created`	A new customer record has been created.
`customer_updated`	A customer record has been modified.

Catalog Events

Event	Description
`item_created`	A new item has been created.
`item_updated`	An item has been modified.
`offer_created`	A new offer has been created.
`offer_updated`	An offer has been modified.
`merchant_created`	A new merchant has been created.
`merchant_updated`	A merchant has been modified.
`campaign_created`	A new campaign has been created.
`campaign_updated`	A campaign has been modified.

Technical Requirements

Endpoint Requirements

Protocol: HTTPS required
Method: POST
Response: Return HTTP 200 to acknowledge receipt
Content-Type: application/json

Failure Handling

Webhooks v2 tracks consecutive failures. If your endpoint fails to respond with a 200 status code for 5 consecutive deliveries, the connection will be automatically deactivated to prevent unnecessary load. Re-activate the connection after resolving the issue with your endpoint.

Processing Notes

Webhooks are delivered as events are processed
Use the webhook_event_id field for idempotency
Ensure your endpoint can handle concurrent requests
All delivery attempts are logged and viewable on the connection's webhook log

Monitoring

View webhook delivery logs on the connection settings page. Each log entry includes:

Event Type - Which event triggered the webhook
Request URL - The destination endpoint
Request Payload - The complete JSON sent
Response Code - HTTP status returned by your endpoint
Response Body - Your endpoint's response
Timestamp - When the webhook was delivered