Tutorials & Solutions
Orders management
Inventory and shipping
Subscriptions
Payments
Catalog
Prices
Rates & Benefits
Insights
Master data
Message Center
Sales Policies
CMS
Checkout
Sellers
Integrations
Authentications
Account management
Billing
Apps
Other

Configuring Feed v3 Hook

Beatriz Silva
Beatriz Silva
Last updated
12/31/2019

The Hook is an extension of the Feed v3, tailored to robust operations that require more complex integrations.

Unlike the feed, its operation doesn't require any reactive commits from users. When a call is correctly placed to an address, the system performs an auto commit.

Its main functionality is avoiding an unnecessary feed query by a system or user without having new events, notifying the configured endpoint whenever an order status update occurs.

Configure at which endpoint you will receive Hook notifications and which events you will be notified about by using the API Hook Configuration.

For configuring and using the Hook, you need to create a Feed v3 and Hook enabled access profile within OMS.
Without any configured filter for the Hook configuration API, the endpoint will be notified of any and all events.

How Hook configuration works

According to the status of the API filter, the Hook notifies the configured endpoint each time a new event is logged on its feed. Due to the infrastructure required to maintain endpoint notifications, there are two scenarios in which the Hook configuration can be removed from your account:

Unsuccessful notifications

If a new event is not correctly notified to the endpoint, the interval for future retries is recalculated based on an internal geometric progression algorithm.

Up to 100 notification attempts can be made for four consecutive days. If these attempts do not work, the Hook configuration will be removed, and VTEX will not send new notifications to the endpoint until a new configuration is implemented.

When notified, the configured endpoint must always respond with server code 200.

Feed without new events

If the configured endpoint is not notified within a 3-day period, meaning that if your feed does not record any new event that qualifies for a notification during the time period, the Hook and Feed v3 configurations are then discarded.

It is imperative to check the defined status filters of the filter object within the Hook API configuration, since the configured status of this object defines which events trigger notifications. It's possible for the configured filter to limit notifications sent to your endpoint, thus impairing the Hook configuration.

Even if it falls into one of above-mentioned scenarios, Hook or Feed configurations with less than three days of runtime will not be removed.

External calls performed by the Hook

Default request example

  • POST
  • Content-Type: application/json
{
   "Domain": "Marketplace",
   "OrderId": "v40484048naf-01",
   "State": "payment-approved",
   "LastChange": "2019-07-29T23:17:30.0617185Z",
   "Origin": {
       "Account": "accountABC",
       "Key": "vtexappkey-keyEDF"
   }
}

Ping

When the hook is configured, VTEX sends a ping to the endpoint given in the configuration call's body, aiming to ensure that it is up and running.

  • POST
  • Content-Type: application/json
{ 
  "hookConfig": "ping" 
}
The given endpoint should return a status 200 for the above mentioned request. Otherwise, saving the configuration won't be possible.

How to use Hook for franchise accounts

We recommend to always configure Hook on the main account. Even in robust operations, configuring Hook on different franchise accounts increases the possibility of the configuration being removed due to lack of endpoints notifications.

A main account on the other hand has a much larger events flow, since it carries all of the franchise accounts orders as well. This ensures that the configured endpoint is constantly notified and that there is greater visibility to commit all the events correctly.

Still got questions?
Ask the community
Find solutions and share ideas in VTEX's community.
Talk to our experts
Get in touch if you have something specific to ask about the platform.
  • PT
  • ES
VTEX website