Webhooks for Ordering Notifications

If a Partner is subscribed to any of the order or orderLine status changes, GiftAPI send out notifications to inform of any order or orderLine status updates.

Update Order Notification/Callback

The system supports callbacks to Partners/Subscribers when changes to the order status have been made to the order or order line level. This allows the subscriber to receive a message when the status has changed.

The partner must supply a public HTTPS endpoint and develop a Listener to receive the callback messages.

This notification service also provides an optional feature for subscriber to supply Open Authentication (OAuth) credentials as an additional layer of security.

The partner is required to answer the below questionnaire, post which onboarding team will configure the credentials. Once configured, partner can conduct a validation test and share results.

1. What security mechanism would partner like to use for receiving notifications on this endpoint? GiftAPI support the below :
   1. Basic (Username/Password)
   2. OAuth (Client Credentials) 
   3. API Key
2. What statuses would Partner like to be onboarded with? GiftAPIs provide order and orderLine level notifications.
3. GiftAPI also support addition of custom headers for additional validation capabilities.

The following tables consists the Order and Order Line events that Partner can subscribe to:

The following table consists the Order and Order Line Payload fields that Partner can subscribe to:

Item Delivery Status Values (Coming Soon)

Delivery statuses for Digital orders:

Delivery statuses for Physical orders

Order Level Payload Sample

2. {
       "event": {
           "entityType": "ORDER",
           "orderId": "01JRZ37TPZEFANBET3490GKT2K",
           "orderNumber": "9733-25549854-9018",
           "externalPONumber": "TSTSUDOo789oCT10000011111",
           "locale": "en_US",
           "orderStatus": "COMPLETED",
           "externalId": "DB3E04AF452E4BA897EE7663C5002",
            "id": "01JF0EEW4CNV2MMCZV35K97D4D"
       }
   } 
   
   
   

OrderLine Payload Sample

2. DigitalPhysical

   {
     "event": {
       "entityType": "ORDERLINE",
       "messageType": "DIGITAL",
       "orderId": "01JRZ2KVAMT6CP080QTB73HQ1Z",
       "orderLineId": "01JRZ2KVAMMGJ4AGJS6FCF5Z9Q",
       "orderLineStatus": "COMPLETED",
       "upc": "07675017464",
       "quantity": 1,
       "faceValue": {
         "value": 20.0,
         "currency": "USD"
       },
       "iid": "76696",
       "eventTimestamp": "2025-04-16T10:35:10.974Z",
       "shippedDate": "2025-04-16T10:34:18.910Z",
       "id": "01JF0EEW4CNV2MMCZV35K97D4D",
       "delivery": {
         "methods": [
           {
             "type": "EMAIL",
             "schedule": "DATE",
             "deliveryStatus": {
               "status": "DELIVERED_OPEN",
               "deliveryTimestamp": "2025-06-11T22:36:12.455887947Z"
             }
           },
           {
             "type": "SMS",
             "deliveryStatus": {
               "status": "DELIVERED",
               "deliveryTimestamp": "2025-06-11T22:36:12.455887947Z"
             }
           }
         ]
       },
       "cardReferenceInfo": [
         {
           "cardReferenceId": "23YFEYDDJDNSKDOSDOWOS546464"
         }
       ]
     }
   }
   
   

   {
       "event": {
           "entityType": "ORDERLINE",
           "messageType": "PHYSICAL",
           "orderId": "01JMR16QVX82P1QF604AK2VM8H",
           "orderLineId": "01JMR16QVY012PDD8TMCVYDQFR",
           "orderLineStatus": "COMPLETED",
           "shippingTrackingInfo": [
               {
                   "shippingTrackingNumber": "948883441903",
                   "shippingURL": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=948883441903",
                   "actualShippingMethod": "UPS Next Day"
               }
           ],
           "upc": "07675018605",
           "quantity": 6,
           "faceValue": {
               "value": 10.0,
               "currency": "USD"
           },
           "iid": "74243",
           "externalLineId": "TEST-EXT-LINEID-001",
           "eventTimestamp": "2025-02-23T00:02:52.417Z",
           "shippedDate": "2025-02-23T00:02:51.940Z",
           "id": "01JMR1TABYE3MD07PZQF70FDR8",
           "delivery": {
               "methods": [
                   {
                       "type": "PHYSICAL",
                       "shipping_fee": {},
                       "physicalMethod": "upsground",
                       "deliveryStatus": {
                           "status": "DELIVERED",
                           "deliveryTimestamp": "2025-06-11T22:36:12.455887947Z"
                       }
                   }
               ]
           },
           "cardReferenceInfo": [
               {
                   "cardReferenceId": "23YFEYDDJDNSKDOSDOWOS546464"
               },
               {
                   "cardReferenceId": "23YFEFBHFKSDW374683SKDOSDOWOS"
               }
           ]
       }
   }