You are here:
Webhooks
The Tradevine API allows you to register webhooks for certain events to allow integrations and apps to remain in sync.
This removes the need for your application to always poll our system, which will increase performance.
Concepts
Tradevine uses the following definitions for webhooks.
Webhook: This is the object that defines what webhook event Tradevine will react to and where we will send it.
Webhook event: The sending of the webbhook. Will have an event type and contain an event payload.
Event type: A type of event we will react to happening. See list of event types here.
Event payload: The data sent in the webhook. The product/sales order property will correspond to the same object in the api.
Event payload
See the different types and values for event types here.
The payload will have the following model. Webhook.
The payload for the event will have one of two types at the moment, either product or sales order.
| Event type(s) | Event payload |
| Product created, Product updated, Product inventory - warehouse stock updated, Product inventory - ATS updated, Product deleted | Model - Product |
| Sales order created, Sales order updated, Sales order status change, Shipment updated, Shipment confirmed | Model - Sales order |
Headers
X-Tradevine-Hmac-SHA256 - For verification of the request. See Receive and verify webhook.
Webhook behavior
Timing and Order
Webhook events are processed asynchronously on our system, meaning webhook events may not arrive in order or take a while after the event is initially triggered.
Webhook event failure and retry
Failure - If we receive a non-2xx http response or a slow response we will fail the webhook event. The exact same payload will be sent again. You will have to handle if we send an older event after the underlying data is updated
Backoff/retry - On failure we will retry the webhook event, with the time between retries increasing. If your endpoint fails to many times in a row, it will be disabled, and need to be reenabled through the Tradevine Api Applications UI
Requirements
Your endpoint must be an HTTPS webhook address with a valid SSL certificate.
Your endpoint must respond with a 2xx within 5 seconds.
Handle duplicate events. We make an effort to not send the same event, but this may happen in some senarios.
Implement reconciliation jobs. Webhooks allow you to not poll all the time, however they are not a perfect system and events may be missed. For this reason you will need to implement reconcilliation jobs.
Testing webhooks
To view an example webhook consumer endpoint please look at our sample application it has an implementation in the Controller/Webhooks section. Please note, this needs implementing into an API as the sample application doesn't handle api calls.
Sending a webhook.
1. Create the webhook subscription - Go to your API application and enter the details under the webhooks section.
a. This will consist of an Event Type, your https url, and optionally and header name and value.
2. Test either with a deployed application or using a service such as (Beeceptor, PageKite, ngrok) to test. Use of these services is at your own risk.
3. Perform the action you subscibed to in the first step. For instance this may be creating a new Product on Tradevine Web UI
Receive and verify webhook. This step is extremely important so you know the request is from us
You may provide one custom header and value. This could be used for an API key or similar.
4. Hash using sha256 on the payload using your client secret. An example of this is in the sample application
a. A C# example
// Read data from request
string payloadString = await Request.Content.ReadAsStringAsync();
// Create a new HMACSHA256 hasher with your Consumer Secret as the key.
var hasher = new HMACSHA256(Encoding.UTF8.GetBytes(Config.Current.ConsumerSecret));
// Convert the payload string into a byte array.
byte[] inputBytes = Encoding.ASCII.GetBytes(payloadString);
byte[] hash = hasher.ComputeHash(inputBytes);
// Turn the hash byte array into a hex-string.
string calculatedHash = BitConverter.ToString(hash).Replace("-", "").ToLower();
// Get the hash sent in the header.
var tradevineHMAC = Request.Headers.GetValues("X-Tradevine-Hmac-SHA256").FirstOrDefault();
// Compare hashes.
var validRequest = tradevineHMAC == calculatedHash;
5. Respond - must be 2xx response. No redirects, these will count as failures.