With webhooks you can receive updates about particular entities. After you subscribed to a webhook you'll be receiving events when the entity is created, updated or deleted.
For example, you can rely on webhooks to trigger an action in your app when an order is created, or when tracking status of shipment is updated. By using webhooks subscriptions you can make fewer API calls overall, which makes sure that your apps are more efficient and update quickly.
You can view this video to better understand how webhooks work in TrackMage.
You can enable the webhook from the Automation / Webhooks page in the TrackMage admin panel --> Add webhook --> Enter Webhook URL -> Select entities and events to start receiving updates.
We currently support either HTTP or HTTPS URLs, so you can have security by using an SSL-enabled URL. To restrict access for your webhook endpoint we allow use two types of authorization:
- Basic - an HTTP authentication using username and password.
- Bearer - an HTTP authentication scheme that involves security tokens called bearer tokens.
For each webhook you can set up frequency of updates.
- Immediately: the update will be sent as soon as a tracking number status changes.
- 5 minutes - 6 hours: Webhook accumulates the updates and will send them in a batch.
How Concurrency works:
Let's say, in the webhook buffer there are 1500 tracking numbers. Before the sending, the buffer is always split into portions or batches. The number of requests depends on the amount of tracking numbers to send and on the batch size. Currently, the batch size is 500. The webhook buffer gets empty on success response. If response status is an error (4xx, 5xx), the tracking numbers will remain in the queue. If the response status is 401 - the webhook will be disabled. Partially submitted data will not be submitted again. For example, if webhook was able to submit 500 tracking numbers out of 1000, on the next call it will submit only remaining 500 (not 1000 like it used to).
Example 1. The concurrency is set to 1 (or none).
The batches will be sent consequently, so requests will not be sent in parallel. The next batch will be sent only after the response from the previous has been received. In case if response status is error it'll stop sending the others.
Example 2. The concurrency is 3 and all requests are sent in parallel.
On error, it will not stop but will try to send the next request. At the end, all not-accepted requests will be scheduled for the next webhook call.
After you configure a webhook subscription, the events that you specified will schedule or send immediately (depended on your webhook settings) a webhook notification. TrackMage sends event driven data to webhook URL via POST method. This notification contains a JSON payload with event data and authorization header (basic or bearer) if Auth Type is set in the webhook settings.
JSON payload is represented by list of objects with four properties:
- "entity"- the entity for which the webhook triggered
- "event" - the event type create/update/delete
- "data" - the entity's data
- "updatedFields" - the list of updated fields codes (empty for create/delete events)
For example, the shipments/update webhook contains:
TrackMage allows to create one webhook for all supported entities and events. But we recommend specifying separate webhooks for different entities and events.
Webhooks are available for the following entities:
Webhooks can be triggered for the following events:
Webhooks are represented by Workflow entity in the TrackMage API.
In API request you should use
type: "webhook" to be sure you work with webhook
In addition to standard Workflow fields, webhook has its own specified properties, which should be used in API requests.
A full list of specified properties can be retrieved by using request to Custom Fields endpoint with GET parameter
Full list of available endpoints to create/update/edit webhooks available on the workflow page.
This example shows you how to retrieve the webhook, validate Basic authentication it and save data to a CSV file.