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 Events Types

Snappy currently supports the following:

Gift Status Events

These events track the core lifecycle of a gift.

Event Name	Description
`gift-status-changed`	Triggered whenever a gift moves to a new stage in the recipient journey

Optional 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.

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

Order Lifecycle Events

These events expose the order behind a claimed gift using the v3 Orders vocabulary. Use them when you integrate at the order level rather than the recipient-facing gift level.

Event Name	Description
`order-status-changed`	Triggered when an order’s status changes (e.g. placed or cancelled).
`order-delivery-status-changed`	Triggered as an order moves through the full delivery lifecycle.

order-status-changed statuses:

Field	Values
`status`	`active`, `cancelled`
`fulfillmentStatus`	`unfulfilled`, `cancelled`

order-delivery-status-changed statuses:

Delivery Status	Description
`confirmed`	The fulfillment request has been received.
`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 Delivery & Fulfillment Events) 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",
    "fulfillmentStatus": "unfulfilled",
    "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"
  }
}

Delivery & Fulfillment Events

These events track the physical movement of a gift after it has been claimed.

Event Name	Description
`gift-delivery-status-changed`	Triggered as the gift moves through the physical shipping process.

Delivery 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.

This event only fires for the inTransit, outForDelivery, and delivered milestones. For the full order-level delivery lifecycle (including confirmed and processing), use the order-delivery-status-changed event under Order Lifecycle Events instead.

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.

Recipient Notification Events

Use these events to track the communications Snappy sends to your recipients.

Event Name	Description
`gift-notification-initial`	The first gift notification was sent.
`gift-notification-reminder`	An automated reminder was sent to a recipient who hasn’t claimed yet.
`gift-notification-resend`	A notification was manually resent via the dashboard or API.
`gift-notification-expiration`	The final “last chance” notification was sent before the gift expiration.

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.

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

Catalog & Stock Events

Use these events to keep your local catalog in sync.

Event Name	Description
`stock-availability-updates`	Triggered when a product’s inventory status changes. This is essential for keeping your local catalog in sync.

Optional statuses:

Inventory Status	Description
`in_stock`	The product is available for ordering.
`stocked_on_demand`	The product is available but may require additional lead time.
`discontinued`	The product is no longer available and will not be restocked.
`out_of_stock`	The product is temporarily unavailable.

Example Payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "stock-availability-updates",
    "target": "string",
    "triggeredAt": "2025-01-22T11:45:00.000Z"
  },
  "eventData": {
    "id": "string",
    "title": "Premium Wireless Headphones",
    "description": "High-quality wireless headphones with noise cancellation",
    "category": "Electronics / Audio / Headphones / Wireless",
    "status": "in_stock",
    "brand": {
      "id": "string",
      "name": "Brand Name"
    },
    "types": [
      {
        "type": "physicalGift"
      }
    ]
  }
}

Recipient Engagement Events

Triggered when a recipient interacts with the platform after claiming their gift, such as sending a message to the gift sender.

Event Name	Description
`gift-thank-you-note-received`	The recipient has written a thank-you note for the sender.

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

Exceptions & Operational Events

Use these events to track critical edge cases in your integration.

Event Name	Description
`order-canceled`	Triggered if an order is canceled by the sender, the system, or due to a fulfillment issue.
`order-out-of-stock`	Triggered if a selected product becomes unavailable before fulfillment. This allows you to proactively notify the sender or offer a replacement.

The eventData for operational events always contains the relevant orderId and companyId so you can map the failure back to the specific order and recipient.

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

Billing Events

Use these events to react to invoicing changes.

Event Name	Description
`gift-invoice-sent`	Triggered when a gift invoice has been sent.

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).

Billing, catalog, and operational events (such as order-canceled and order-out-of-stock) do not carry gift metadata. Map these back to your records using the orderId or companyId 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

Migrating to V3

Webhooks & Events

Webhook Event Types: Real-Time Gift Lifecycle

Event Structure

Webhooks and Events Types

Gift Status Events

Order Lifecycle Events

Delivery & Fulfillment Events

Recipient Notification Events

Catalog & Stock Events

Recipient Engagement Events

Exceptions & Operational Events

Billing Events

Metadata in Webhooks

​Event Structure

​Webhooks and Events Types

​Gift Status Events

​Order Lifecycle Events

​Delivery & Fulfillment Events

​Recipient Notification Events

​Catalog & Stock Events

​Recipient Engagement Events

​Exceptions & Operational Events

​Billing Events

​Metadata in Webhooks

Event Structure

Webhooks and Events Types

Gift Status Events

Order Lifecycle Events

Delivery & Fulfillment Events

Recipient Notification Events

Catalog & Stock Events

Recipient Engagement Events

Exceptions & Operational Events

Billing Events

Metadata in Webhooks