Gift Webhook Events

The gift entity has the following events:

Gift Status Changed

Event name: gift-status-changed

Receive this event when a gift status has changed. The status can be one of the following:

unopened: The gift has been sent but not yet opened by the recipient
unwrapped: The gift has been opened but not yet claimed
opened: The gift has been opened by the recipient
claimed: The gift has been claimed by the recipient
expired: The gift has expired before being claimed

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-status-changed",
    "target": "string",
    "triggeredAt": "2025-01-15T14:44:00.138Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "status": "opened",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "integrationData": "custom-value",
      "recipientContext": "anniversary-gift"
    }
  }
}

Metadata

The metadata object allows you to attach custom key-value pairs to gifts. This feature enables you to:

Store additional gift-specific information that isn't covered by standard fields
Include custom data that will be sent in webhook notifications
Track and manage gift-related data specific to your integration needs

Technical specifications:

Keys must be alphanumeric and up to 40 characters
Values must be alphanumeric and up to 500 characters
Maximum 50 key-value pairs allowed per gift

Example use cases:

Store internal reference IDs or tracking numbers and get them in the webhooks
Add custom categorization or tagging
Include integration-specific data for webhook processing
Attach additional recipient or gift context

Gift Delivery Status Changed

Event name: gift-delivery-status-changed

Receive this event when a gift delivery status has changed. The delivery status can be one of the following:

orderReceived: The gift order has been received
processing: The gift is being processed for shipping
inTransit: The gift is in transit to the recipient
outForDelivery: The gift is out for delivery
delivered: The gift has been delivered to the recipient

Example payload:

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

Invoice Sent

Event name: gift-invoice-sent

Receive this event when a gift invoice has been sent to the company.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-invoice-sent",
    "target": "string",
    "triggeredAt": "2025-01-17T15:53:28.068Z"
  },
  "eventData": {
    "companyId": "string",
    "invoiceId": "string"
  }
}

Gift Notification Events

Gift Notification Reminder Sent

Event name: gift-notification-reminder-sent

Receive this event when a reminder notification has been sent to the gift recipient.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-notification-reminder-sent",
    "target": "string",
    "triggeredAt": "2025-01-19T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "integrationData": "custom-value",
      "recipientContext": "anniversary-gift"
    }
  }
}

Gift Notification Expiration Sent

Event name: gift-notification-expiration-sent

Receive this event when an expiration notification has been sent to the gift recipient.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-notification-expiration-sent",
    "target": "string",
    "triggeredAt": "2025-01-19T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "integrationData": "custom-value",
      "recipientContext": "anniversary-gift"
    }
  }
}

Gift Notification Resend Sent

Event name: gift-notification-resend-sent

Receive this event when a gift notification has been resent to the recipient.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-notification-resend-sent",
    "target": "string",
    "triggeredAt": "2025-01-19T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "integrationData": "custom-value",
      "recipientContext": "anniversary-gift"
    }
  }
}

Gift Notification Initial Sent

Event name: gift-notification-initial-sent

Receive this event when the initial gift notification has been sent to the recipient.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "gift-notification-initial-sent",
    "target": "string",
    "triggeredAt": "2025-01-19T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "metadata": {
      "internalReferenceId": "REF123456",
      "customCategory": "employee-recognition",
      "integrationData": "custom-value",
      "recipientContext": "anniversary-gift"
    }
  }
}

Thank You Note Created

Event name: thank-you-note-created

Receive this event when a thank you note has been created by the gift recipient.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "thank-you-note-created",
    "target": "string",
    "triggeredAt": "2025-01-18T10:30:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "thankYouNote": "string"
  }
}

Order Canceled

Event name: order-canceled

Receive this event when an order is canceled. This can happen when a gift order is canceled by the sender, the system, or due to fulfillment issues.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "order-canceled",
    "target": "string",
    "triggeredAt": "2025-01-20T09:15:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "orderId": "string"
  }
}

Order Out of Stock

Event name: order-out-of-stock

Receive this event when an order cannot be fulfilled because the selected product is out of stock. This allows you to take action such as notifying the sender or offering alternative products.

Example payload:

{
  "webhookData": {
    "id": "string",
    "eventType": "order-out-of-stock",
    "target": "string",
    "triggeredAt": "2025-01-21T14:20:00.000Z"
  },
  "eventData": {
    "companyId": "string",
    "giftId": "string",
    "orderId": "string"
  }
}

Stock Availability Updates

Event name: stock-availability-updates

Receive this event when a product's stock availability has changed. This allows you to keep your product catalog in sync with real-time inventory changes.

The status can be one of the following:

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

Notes

The eventData contains the full product/variant details fetched from the product catalog at the time of the stock change.
If a product cannot be found (e.g., it was deleted), the payload will contain minimal data with status set to out_of_stock.