Documentation Index
Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
Use this file to discover all available pages before exploring further.
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 |
| 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. |
{
"webhookData": {
"id": "wh_12345",
"eventType": "gift-status-changed",
"triggeredAt": "2025-01-15T14:44:00Z"
},
"eventData": {
"giftId": "gft_12345",
"status": "claimed",
"metadata": {
"internalReferenceId": "REF-ABC-123"
}
}
}
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 Status | Description |
|---|
orderReceived | The fulfillment request has been received. |
processing | The item is being prepared for shipment. |
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. |
{
"webhookData": {
"id": "string",
"eventType": "gift-delivery-status-changed",
"target": "string",
"triggeredAt": "2025-01-16T12:50:40.313Z"
},
"eventData": {
"companyId": "string",
"giftId": "string",
"deliveryStatus": "outForDelivery",
"outForDeliveryDate": "2025-01-16T08:00:00.000Z"
}
}
Recipient Notification Events
Use these events to track the communications Snappy sends to your recipients.
| Event Name | Description |
|---|
gift-notification-initial-sent | The first gift notification was sent. |
gift-notification-reminder-sent | An automated reminder was sent to a recipient who hasn’t claimed yet. |
gift-notification-resend-sent | A notification was manually resent via the dashboard or API. |
gift-notification-expiration-sent | The final “last chance” notification was sent before the gift expiration. |
{
"webhookData": {
"id": "wh_12345",
"eventType": "gift-notification-reminder-sent",
"target": "https://your-domain.com/webhooks",
"triggeredAt": "2025-01-19T10:30:00.000Z"
},
"eventData": {
"companyId": "com_12345",
"giftId": "gft_12345",
"metadata": {
"internalReferenceId": "REF123456",
"customCategory": "employee-recognition",
"recipientContext": "anniversary-gift"
}
}
}
Stock Availability 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 |
| 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. |
{
"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 |
|---|
thank-you-note-created | The recipient has written a thank-you note for the sender. |
{
"webhookData": {
"id": "string",
"eventType": "thank-you-note-created",
"target": "string",
"triggeredAt": "2025-01-18T10:30:00.000Z"
},
"eventData": {
"companyId": "string",
"giftId": "string",
"thankYouNote": "string"
}
}
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 will always contain the relevant giftId and companyId so you can map the failure back to the specific recipient, along with any custom metadata you provided during creation.
{
"webhookData": {
"id": "wh_12345",
"eventType": "order-canceled",
"target": "https://your-domain.com/webhooks",
"triggeredAt": "2025-01-20T15:00:00.000Z"
},
"eventData": {
"companyId": "com_12345",
"giftId": "gft_12345",
"cancelReason": "Fulfillment center rejected address",
"metadata": {
"internalReferenceId": "REF-ABC-123"
}
}
}
As discussed in the API Standards section, any metadata you attach during gift creation will be included in the eventData of nearly all webhook notifications. This ensures you can always map a Snappy event back to your internal IDs (e.g., internalReferenceId).
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.
