Webhook Event Types: Real-Time Gift Lifecycle

Event Structure

Every payload received at your endpoint follows this standard structure:

Field	Type	Description
`webhookData`	Object	Metadata about the webhook delivery (ID, type, timestamp).
`eventData`	Object	The core payload containing entity-specific information (Gift ID, Status, etc.).

Use these example payloads to build and test your webhook listener locally before receiving real events. Tools like Ngrok or Webhook.site let you simulate incoming webhook calls by sending these payloads directly to your local endpoint - no real gift sends required.

Webhooks and Event Types

Snappy webhook events fall into four groups: Order & Fulfillment for the order and its physical fulfillment, Gift & Recipient for the recipient-facing gift experience, Catalog & Inventory for keeping your local catalog in sync, and Account & Billing for account and invoicing changes.

Order & Fulfillment

Track the order and its physical fulfillment - from placement through carrier delivery.

Event Name	Description
`order-status-changed`	Triggered when an order’s status changes (e.g., `active`, `completed`, `cancelled`).
`order-delivery-status-changed`	Triggered when the physical shipping state of an order updates with the carrier (e.g., `in_transit`, `out_for_delivery`, `delivered`).
`order-canceled`	Triggered when an order is canceled by the sender, the system, or due to a fulfillment issue and order processing halts.
`order-out-of-stock`	Triggered when a selected product becomes unavailable before fulfillment. This allows you to proactively notify the sender or offer a replacement.

order-status-changed statuses:

Status	Description
`active`	Being processed or in fulfillment.
`completed`	Fulfilled and finalized.
`cancelled`	Cancelled before fulfillment.

order-delivery-status-changed delivery statuses:

Delivery Status	Description
`processing`	The item is being prepared for shipment.
`in_transit`	The item has been picked up by the carrier.
`out_for_delivery`	The item is expected to be delivered today.
`delivered`	The item has reached its final destination.

Order delivery statuses use the public v3 snake_case vocabulary, whereas the gift-delivery-status-changed event (under Gift & Recipient) reports the recipient-facing camelCase milestones.

order-status-changed Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "order-status-changed",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-16T12:50:40.313Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "orderId": "ord_12345",
    "status": "active",
    "metadata": {
      "internalReferenceId": "REF-ABC-123"
    }
  }
}

order-delivery-status-changed Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "order-delivery-status-changed",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-16T12:50:40.313Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "orderId": "ord_12345",
    "deliveryStatus": "out_for_delivery",
    "triggerEvent": "updated",
    "outForDeliveryDate": "2025-01-16T08:00:00.000Z",
    "estimatedDeliveryDate": "2025-01-17T00:00:00.000Z"
  }
}

order-canceled Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "order-canceled",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-20T15:00:00.000Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "orderId": "ord_12345",
    "cancellationReason": "customer_requested"
  }
}

order-out-of-stock Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "order-out-of-stock",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-20T15:00:00.000Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "orderId": "ord_12345"
  }
}

Gift & Recipient

Track the recipient-facing gift experience - from the initial notification through claim, delivery, and thank-you.

Event Name	Description
`gift-status-changed`	Triggered when the recipient progresses through the gift experience (e.g., opened, claimed, swapped).
`gift-delivery-status-changed`	Triggered when the delivery status of a physical or digital gift updates.
`gift-notification-initial`	Triggered when the first gift notification email or text is sent to the recipient.
`gift-notification-reminder`	Triggered when an automated reminder notification is sent to a recipient who hasn’t claimed their gift yet.
`gift-notification-resend`	Triggered when a gift notification is manually re-sent (e.g., via dashboard or API action) to a recipient who hasn’t claimed their gift yet.
`gift-notification-expiration`	Triggered when a final, “last chance” expiration notification is sent to a recipient who hasn’t claimed their gift yet before it expires.
`gift-thank-you-note-received`	Triggered when a recipient writes and submits a thank-you note for their gift.

gift-status-changed statuses:

Status	Description
`unopened`	The gift has been sent but the recipient has not clicked the link.
`unwrapped`	The recipient has clicked the link but has not yet viewed the gift options.
`opened`	The recipient has viewed the available gift options.
`claimed`	The recipient has selected a gift and provided their details.
`expired`	The gift reached its expiration date without being claimed.

gift-delivery-status-changed statuses:

Delivery Status	Description
`inTransit`	The item has been picked up by the carrier.
`outForDelivery`	The item is expected to be delivered today.
`delivered`	The item has reached its final destination.

gift-delivery-status-changed only fires for the inTransit, outForDelivery, and delivered milestones. For the full order-level delivery lifecycle (including confirmed and processing), use order-delivery-status-changed under Order & Fulfillment.

gift-notification-* event data fields:

Field	Type	Notes
`companyId`	string	The company that owns the gift.
`giftId`	string	The gift the notification relates to.
`sendingChannel`	string	The channel used to deliver the notification (e.g. `email`, `sms`).
`giftLink`	string	The recipient-facing link included in the notification.
`reminderType`	string	The reminder variant. Present on `gift-notification-reminder` only.
`cadence`	number	Sequence number of the reminder/expiration notice. Present on `gift-notification-reminder` and `gift-notification-expiration`.
`metadata`	object	Any custom metadata attached at gift creation.

gift-status-changed Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "gift-status-changed",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-15T14:44:00Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "giftId": "gft_12345",
    "status": "claimed",
    "metadata": {
      "internalReferenceId": "REF-ABC-123"
    }
  }
}

gift-delivery-status-changed Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "gift-delivery-status-changed",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-16T12:50:40.313Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "giftId": "gft_12345",
    "deliveryStatus": "outForDelivery",
    "triggerEvent": "updated",
    "outForDeliveryDate": "2025-01-16T08:00:00.000Z",
    "estimatedDeliveryDate": "2025-01-17T00:00:00.000Z"
  }
}

deliveredAt is included when deliveryStatus is delivered; outForDeliveryDate when outForDelivery. triggerEvent is created for the first tracking update and updated for subsequent ones.

gift-notification-reminder Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "gift-notification-reminder",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-19T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "giftId": "gft_12345",
    "cadence": 1,
    "sendingChannel": "email",
    "reminderType": "first-reminder",
    "giftLink": "https://gift.snappy.com/g/abc123",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "recipientContext": "anniversary-gift"
    }
  }
}

gift-thank-you-note-received Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "gift-thank-you-note-received",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-18T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "giftId": "gft_12345",
    "thankYouNote": "Thank you so much for the thoughtful gift!"
  }
}

Catalog & Inventory

Use these events to keep your local catalog in sync with Snappy’s.

Event Name	Description
`stock-availability-updates`	Triggered when a product’s availability status changes to either in-stock or out-of-stock. Essential for local catalog sync.

High-volume event. stock-availability-updates can fire thousands of times in a short window — for example, during bulk catalog syncs, brand rollouts, or inventory reconciliations. Make sure your webhook endpoint can absorb bursts: queue-based ingestion, idempotent handlers, and generous retry tolerance. If real-time stock accuracy isn’t a hard requirement, a nightly Bulk Catalog Export may be a simpler fit.

How the status field signals availability: The status field is only present when a product goes out of stock. When present, its value is always out_of_stock. Absence of status means the product is in stock and available for ordering.

`status`	Meaning
(field absent)	The product is in stock and available.
`out_of_stock`	The product is out of stock and cannot be ordered.

stock-availability-updates Example Payload: The eventData matches the response shape of the V2 GET /variants/{variantId} endpoint - the same product-and-variants object your integration already uses elsewhere. The example below shows the in-stock case (no status field). When a product goes out of stock, an additional field "status": "out_of_stock" is included at the top of eventData.

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "stock-availability-updates",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-22T11:45:00.000Z"
  },
  "eventData": {
    "id": "prodSample01",
    "title": "Insulated Stainless Tumbler 30oz",
    "category": "Swag",
    "types": ["physical", "on-demand-plus-swag"],
    "coverImage": {
      "type": "image",
      "publicCloudinaryId": "sample-product-image-1",
      "src": "https://example.com/images/sample-product-image-1.png",
      "position": 1
    },
    "mediaItems": [
      {
        "type": "image",
        "publicCloudinaryId": "sample-product-image-1",
        "src": "https://example.com/images/sample-product-image-1.png",
        "position": 1
      },
      {
        "type": "image",
        "publicCloudinaryId": "sample-product-image-2",
        "src": "https://example.com/images/sample-product-image-2.png",
        "position": 2
      }
    ],
    "brand": {
      "id": "brandSample01",
      "name": "Sample Brand",
      "description": null
    },
    "tags": [],
    "notices": {},
    "variants": [
      {
        "id": "varSample01",
        "title": "Insulated Stainless Tumbler 30oz - Black",
        "types": ["physical", "on-demand-plus-swag"],
        "category": "Swag",
        "information": {
          "including": null,
          "description": "A double-wall stainless tumbler with a push-on lid and slide closure.",
          "features": null,
          "specifications": {
            "dimensions": "8in H x 4in W",
            "materials": "Stainless steel",
            "weight": "28oz"
          }
        },
        "mediaItems": [
          {
            "type": "image",
            "publicCloudinaryId": "sample-variant-image-1",
            "src": "https://example.com/images/sample-variant-image-1.png",
            "position": 1
          }
        ],
        "brand": {
          "id": "brandSample01",
          "name": "Sample Brand",
          "description": null
        },
        "tags": [],
        "notices": {},
        "optionAttributes": {
          "color": "black",
          "size": "30oz"
        },
        "pricing": {
          "US": {
            "cost": 45,
            "ddp": 0,
            "shipping": 9,
            "totalTax": 4.5,
            "totalFee": 6.75,
            "totalFinalCost": 56.25,
            "totalFinalCostNoTax": 51.75
          }
        },
        "supportedCountries": [
          { "countryCode": "US" },
          { "countryCode": "CA" },
          { "countryCode": "GB" }
        ]
      }
    ]
  }
}

Account & Billing

Events related to your Snappy account and gift billing.

Event Name	Description
`gift-invoice-sent`	Triggered when a billing invoice for a claimed gift is generated and dispatched to your account.

gift-invoice-sent Example Payload:

{
  "webhookData": {
    "id": "wh_12345",
    "eventType": "gift-invoice-sent",
    "target": "https://your-domain.com/webhooks",
    "triggeredAt": "2025-01-21T09:15:00.000Z"
  },
  "eventData": {
    "companyId": "com_12345",
    "invoiceId": "inv_12345"
  }
}

Metadata in Webhooks

As discussed in the API Standards section, any metadata you attach during gift creation is echoed back in the eventData of the gift-lifecycle, notification, and shipping events - specifically gift-status-changed, order-status-changed, the gift-notification-* events, gift-delivery-status-changed, and order-delivery-status-changed. This ensures you can always map a Snappy event back to your internal IDs (e.g., internalReferenceId).

Catalog, billing, and operational events (such as stock-availability-updates, gift-invoice-sent, order-canceled, and order-out-of-stock) do not carry gift metadata. Map these back to your records using the orderId, companyId, or product id included in the payload.

Proactive Support: By listening for order-out-of-stock or expired events, your system can automatically trigger follow-up actions, ensuring a high-quality experience even when things don’t go as planned.

Welcome

Start building

Our API Standards

Webhooks & Events

Webhook Event Types: Real-Time Gift Lifecycle

Event Structure

Webhooks and Event Types

Order & Fulfillment

Gift & Recipient

Catalog & Inventory

Account & Billing

Metadata in Webhooks

​Event Structure

​Webhooks and Event Types

​Order & Fulfillment

​Gift & Recipient

​Catalog & Inventory

​Account & Billing

​Metadata in Webhooks

Event Structure

Webhooks and Event Types

Order & Fulfillment

Gift & Recipient

Catalog & Inventory

Account & Billing

Metadata in Webhooks