Use this API to find webhook events that Dsco sent to you or that Dsco attempted to send to you but didn't succeed.

 The Find Webhook History API documents the API's URL, it's arguments/return values and how to interact with it (GET, POST, PUT, etc.) in the Dsco Interactive Playground.

Overview

This API allows you to search for  webhook events Dsco sent to you or tried to send to you.  It has many uses and thus is a bit complicated.  The following sections will break down the attributes and then at the bottom you will find use cases and the various parameters that should be used by each use case.  If it all seems too much for you then just jump down to the use cases and start there.

Pagination

If you are trying to get the next page of results, the only param you  need to pass in is the pageId  param.  Please read the pageId  parameter below to understand how to page through large result sets.  Pay special attention to the caveat about timing out looping through lots of pages.

Parameters
These parameters are additive in filtering the results unless an attribute specifically calls out where one or the other will be used in certain cases or where only a specific subset of the attributes will be used in certain cases.

  • pageId
    When results are returned and there is more than one page of results, pass the returned pageId in on the next call to this API in order to loop through each page of results one at a time.  You don't need to pass any params but the pageId on subsequent page requests.  Please be aware that there is a time limit for you to call to get the next page of results.  That time limit is five minutes.  Also, we will reject any request to get more than one day's worth of results unless you are searching for webhooks around a specific object such as an item or order.  If you need to get more than one day, please simply make progressive calls back through time, first getting the last 24 hours and then looping through all the pages and then when done making a new API call to get the previous day and so on.
  • compress
    If true, compress the results.

    The results differ depending on whether you want to get the list of webhookhistory objects back compressed or not.  Due to the size of objects in the array  it is recommended that you set the compressed attribute to true.

    If compress is true the result will either have the webhookHistory attribute set or it will have the base64EncodedCompressedWebhookHistory attribute set.

    The webhookHistory attribute, if present, is the list of WebhookHistory objects for this page of results.

    The base64EncodedCompressedWebhookHistory, if present, is a base64 encoded string of the GZip compressed itemInventory results.  So, first decode this base64 string into a byte array and then decompress it using the gzip algorithm.  The result will be an array of WebhookHistory objects.
  • webhookUuids
    This attribute restricts the result to just the webhooks associated with the specific webhooks with the webhookUuid values.  You can restrict the results to just a specific webhook or list of webhooks by passing in each desired webhook's webhookUuid.  You can get the webhookUuid of a webhook object by calling the ListAllWebhooks API and each object will have a webhookUuid.
  • webhookEventTypes 
    This parameter is a list of eventTypes to restrict the result to.  So, if you don't want to go to the trouble of specifying the exact webhook by its webhookUuid you can instead just say what kind of webhook you want to restrict the search to.  So, let's say I only want to search within  inventory updated webhooks then I'd pass in INVENTORY_UPDATED.  The webhook event types are documented in the Webhook Event JSON Object on the event attribute.
  • startDate
    This attribute or invocationStartDate is always required. The start date, inclusive, to start searching from rounded down to the nearest whole second.  This attribute does not use the invocationDate to search on, it uses the date the event arrived in the search database.  This is done to prevent race conditions around replication delays in the Dsco system.  Note that unless you are searching for a specific object, specifying a search window greater than one day will be rejected.
  • endDate
    The end date, exclusive, to search up until, rounded down to the nearest whole second. If startDate is provided and endDate is not then "now" is assumed as the endDate. This attribute does not use the invocationDate to search on, it uses the date the event arrived in the search database.  This is done to prevent race conditions around replication delays in the Dsco system.  Note that unless you are searching for a specific object, specifying a search window greater than one day will be rejected.
  • invocationStartDate
    This attribute or startDate is always required.  The starte date, inclusive, to start searching from rounded down to the nearest whole second using the actual time the webhook event was sent (or attempted to send).  This attribute is subject to replication delays and it is not recommended that you search for an invocationDate that is within five minutes of the time of the search or your results may not be deterministic. Note that unless you are searching for a specific object, specifying a search window greater than one day will be rejected.
  • invocationEndDate
    The end date, exclusive, to search up until rounded down to the nearest whole second using the actual time the webhook event was sent (or attempted to send).  This attribute is subject to replication delays and it is not recommended that you search for an invocationDate that is within five minutes of the time of the search or your results may not be deterministic. Note that unless you are searching for a specific object, specifying a search window greater than one day will be rejected.
  • success
    A boolean that if set to true will filter results to only those Wehbook Events that had one of these explicit success http response status codes (and if false, will return all those without one of these success http status codes): 200, 201, 202, 203, 204, 205
  • httpStatus
    One of these enumerated values; used to filter results to only webhook events whose HTTP status code is in one of these bucket:
    • SUCCESS: 200, 201, 202, 203, 204 or 205
    • REDIRECT_ERRORS: 300, 301, 302, 303, 304, 305, 306, 307, 308
    • CLIENT_ERRORS: any 400 level HTTP status code
    • SERVER_ERRORS: any 500 level HTTP status code
    • ALL_ERRORS: any non-200 level HTTP status code
  • httpStatusCodes
    This is a list of http status codes to be included in the search.
  • dscoAccountId
    Pass this in to filter to only webhook events associated with your partner with this dscoAccountId.

    If provided, you must include the webhookEventTypes attribute containing only types that result in the searching of the same objects or you must provide webhookUuids where all the webhooks included result in the same object payload type being sent in the webhook.  

    For example, webhookEventTypes could be INVENTORY_UPDATED or it could be ORDER_CREATED or it could be ORDER_CREATED and ORDER_UPDATED but it could not be INVENTORY_UPDATED and ORDER_CREATED as that would result in searching for different object types for this partner which is not supported.
  • dscoTradingPartnerId
    Pass this in to filter to only webhook events associate with your partner with this dscoTradingPartnerId.

    If provided, you must include the webhookEventTypes attribute containing only types that result in the searching of the same objects or you must provide webhookUuids where all the webhooks included result in the same object payload type being sent in the webhook.  

    For example, webhookEventTypes could be INVENTORY_UPDATED or it could be ORDER_CREATED or it could be ORDER_CREATED and ORDER_UPDATED but it could not be INVENTORY_UPDATED and ORDER_CREATED as that would result in searching for different object types for this partner which is not supported.
  • findSpecificObject
    A true/false flag that if true you want to filter out the results to just find webhook events that were sent for a specific object such as an order or a specific item's inventory changes.  If this is true, you must provide specificObjectType, specificObjectIdName, specificObjectId and possibly specificObjectRetailerId/specificObjectRetailerTradingPartnerId (see attributes for more details).

    Note that all other attributes except pageId/startDate/endDate/invocationStartDate/invocationEndDate are ignored if this flag is set to true.

  • specificObjectType
    Ignored unless findSpecificObject is true.  The attribute indicates what type of specific object you are searching for, one of these enumerated values (case matters)...
    • Inventory
    • Order
    • Invoice
    • OrderLineItemStatusChanges
  • specificObjectIdName
    You must specify what identifier you want to use to find the webhook events associated with the specific object in question and the enumerated name values differ depending on what specificObjectType you provided.  If specificObjectType is...
    • Inventory then these are the valid enumerated values indicating what value is in the specificObjectId (case matters)
      • dscoItemId
      • sku
      • partnerSku
        If provided and you are a supplier then you must provide either specificObjectRetailerId or specificObjectRetailerTradingPartnerId to delineate which retailer the partnerSku value is associated with
      • upc
      • ean
      • mpn
      • gtin
      • isbn
    • Order then these are the valid enumerated values indicating what value is in the specificObjectId (case matters)
      • poNumber
      • supplierOrderNumber
      • consumerOrderNumber
    • Invoice then these are the valid enumerated values indicating what value is in the specificObjectId (case matters)
      • invoiceId
      • dscoInvoiceId
      • poNumber
      • sellerInvoiceNumber
      • supplierOrderNumber
      • consumerOrderNumber
    • OrderLineItemStatusChanged then these are the valid enumerated values indicating what value is in the specificObjectId (case matters)
      • poNumber
      • supplierOrderNumber
      • consumerOrderNumber
  • specificObjectId
    Find only webhook events with this specific identifier (such as a sku or a poNumber, etc.).  Please see findSpecificObject attribute above.
  • specificObjectRetailerId
    This is only used if the partner making the API call is a supplier and specificObjectType passed in was Inventory and specificObjectIdName was partnerSku.  Please see findSpecificObject attribute above.
  • specificObjectRetailerTradingPartnerId
    This is only used if the partner making the API call is a supplier and specificObjectType passed in was Inventory and specificObjectIdName was partnerSku.  Please see findSpecificObject attribute above.

Output Object

The result of calling this API is the PagedWebhookHistoryResult JSON Object. It will contain the list of WebhookEvent JSON Objects returned from this API for the specified page of results if any.

Use Case - Find all failed Webhook Events

This is the most common use case for this API.  Dsco cannot guarantee delivery of absolutely every Webhook to your endpoint.  Many things can cause an individual Webhook event to not get delivered to your endpoint.  Here's a recommended methodology to ensure you never miss a Webhook event.

  1. Register the webhook you want sent to your endpoint using the Add Webhook API (let's say we created one of type INVENTORY_UPDATED)
  2. Write code to every hour call this API to find any webhooks that couldn't be delivered
    1. pass in startDate of an hour ago rounded down to the nearest second
    2. pass in endDate of now rounded down to the nearest second
    3. store the endDate to use as the startDate for the next search an hour from now
    4. pass in success with a value of false
    5. Get the first response and if there's a pageId, continue making calls until you run out of pages and make sure that you make each subsequent call within five minutes of the last call or your search will be remove from memory and future calls with a timed-out pageId will fail

Use Case - replay Webhook Events over a period of time

Let's say that something bad happened in your system and although you were returning an HTTP 200 code back, the webhook events in your system were not being processed correctly over the past three days.  To recover, you would need to go back and get all webhook events for the past three days and process them.  Here's how you would do that...

  1. get the first day's webhook events (remember you can't get more than one day's results unless you are searching for webhook events for a specific object)
    1. pass in startDate from the start of the day rounded down to the nearest second
    2. pass in endDate from the end of the day rounded down to the nearest second
    3. page through the results, making sure you call the next paged API within five minutes to prevent the paged search results from timing out and disappearing
  2. then do steps 1.1  - 1.3 again for the next 24 hour period
  3. then do steps 1.1 - 1.3 again for the last 24 hour period

Use Case - get Webhook Events for a specific trading partner

Let's say you want to find all order webhook events in the last hour for a specific trading partner whose dscoTradingPartnerId is MyCoolTradingPartnerId.

  1. pass in startDate from an hour ago rounded down to the nearest second
  2. don't pass in endDate and it will default to NOW
  3. pass in dscoTradingPartnerId with a value of MyCoolTradingPartnerId
  4. pass in webhookEventTypes with the values ORDER_CREATED and ORDER_UPDATED
  5. you will get back any webhook order events associated with this dscoTradingPartnerId

Use Case - Find Webhook Events for a specific inventory update

Let's say you think you should have gotten a webhook event letting you know that the inventory changed for a specific item with a sku of aaa-bbb-ccc and so you want to see all recent webhook events for that item.  Here's what you do...

  1. pass in startDate from when you think it's back far enough to find them
  2. pass in an endDate that bookends the timeframe in question or don't pass this in if you want it to go up until "now" which is really "now" minus up to five minutes because of possible replication delays
  3. pass in findSpecificObject with a value of true
  4. pass in specificObjectType with a value of Inventory
  5. pass in specificObjectIdName with value of sku
  6. pass in specificObjectId with the value of aaa-bbb-ccc
  7. you will get back any item inventory update events with that sku

Use Case - Find Webhook Events for a specific order

Let's say you think you should have gotten a webhook letting you know about an update to a specific order with a poNumber of 11223344 and so you want to see all recent webhook events for that order.  Here's what you do...

  1. pass in startDate from when you think it's back far enough to find them
  2. pass in an endDate that bookends the timeframe in question or don't pass this in if you want it to go up until "now" which is really "now" minus up to five minutes because of possible replication delays
  3. pass in findSpecificObject with a value of true
  4. pass in specificObjectType with a value of Order
  5. pass in specificObjectIdName with value of poNumber
  6. pass in specificObjectId with the value 11223344
  7. you will get back any order webhook events with that poNumber

Use Case - Find Webhook Events for a specific invoice

Let's say you think you should have gotten a webhook event letting you know about an update to a specific invoice with an invoiceId of 1000342 and so you want to see all recent webhook events for that invoice.  Here's what you do...

  1. pass in startDate from when you think it's back far enough to find them
  2. pass in an endDate that bookends the timeframe in question or don't pass this in if you want it to go up until "now" which is really "now" minus up to five minutes because of possible replication delays
  3. pass in findSpecificObject with a value of true
  4. pass in specificObjectType with a value of Invoice
  5. pass in specificObjectIdName with value of invoiceId
  6. pass in specificObjectId with the value 1000342
  7. you will get back any invoice webhook events with that invoiceId

Use Case - Find Webhook Events for a specific orderLineItemStatusChange

Let's say you think you should have gotten a webhook event letting you know about an update to a specific line item of an order whose poNumber is 999222 and so you want to see all recent OrderLineItemStatusChange webhook events for that order.  Here's what you do...

  1. pass in startDate from when you think it's back far enough to find them
  2. pass in an endDate that bookends the timeframe in question or don't pass this in if you want it to go up until "now" which is really "now" minus up to five minutes because of possible replication delays
  3. pass in findSpecificObject with a value of true
  4. pass in specificObjectType with a value of OrderLineItemStatusChanged
  5. pass in specificObjectIdName with value of poNumber
  6. pass in specificObjectId with the value 999222
  7. you will get back any webhook events for line item status changes associated with that poNumber
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.